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The kernel is based on an event: driven dispatcher that does priority~ 
driven scheduling. Time slicing is done by a timer event that occurs 
once per TICK, typically every 16 to 20 milliseconds (implementation 
dependent). Scheduling of equal priority processes is done in a round: 
‘robin fashion. 


Pipe File System 


FlexOS performs process communication and synchronization through 
named pipes. These in-memory files are available to pass data from 
One process to another or to synchronize activities when acting as 
semaphores. 


Console File System 


The FlexOS console system provides dedicated functions designed 
specifically for the fast manipulation of bit-mapped and = character- 
Oriented displays. A single call can copy or modify a screen region 
ranging in size from a single character cell to the entire screen. These’ 
functions give you a consistent, hardware-independent interface to the 
computer's interactive devices without sacrificing program portability. 


The console system also provides window management facilities. that 
allow applications to create and manage multiple virtual consoles. 


Intended Audience and Manual Organization 


This manual (hereinafter referred to as the Programmer's Guide) is 
written for the programmer whose goal is to write applications and 
utilities to run under the FlexOS operating system. The Programmer's 
Guide anticipates, but does not require, a working knowledge of the C 
programming language. 


The Programmer's Guide is organized as follows: 


section 1 Terms and conventions used in this manual; file system 


characteristics; summary of Supervisor calls and tables. 


Section 2 Disk Resource Manager 

Section 3 Console Resource Manager 
Section 4 Pipe Manager 

Section 5 Process Management 

Section 6 Miscellaneous Device Management 
Section 7 Supervisor call reference 

Section 8 system table reference 


Appendix A FlexOS character codes 
Appehdix B. System return and error codes 
Appendix C  FlexOS country codes 


The FlexOS Documentation Set 


The Programmer's Guide is one of several manuals in the FlexOS 
documentation set. The other documents are: 


-@ FlexOS User's Guide: The user's reference for FlexOS operation. 


vi 


The User’s Guide describes the command shell, advanced FlexOS 
concepts, and command files. It also provides an overview of 
system manager functions. | 


FlexOS System Guide: The guide to FlexOS = system 
implementation for an original equipment manufacturer or driver 
writer. Information presented in this guide includes driver and 
supervisor interfaces, FlexOS’s driver services, and how to 
construct a boot loader. 


FlexOS Supplements: Microprocessor-dependent supplements to 
the Programmer's Guide and the FlexOS System Guide. 


FlexOS Programmer's Utilities Guides: The reference to FlexOS 
assembly language programming tools. There is a separate 
utilities guide for each microprocessor supported by FlexOS. 


Foreword 


FlexOS™ is a real-time, multitasking operating system designed for 
single-user and multiuser microcomputer systems. The programming 
interface to FlexOS is CPU- and peripheral-independent so you can 
develop programs that are portable between machines with different 
components and processors. 


FlexOS Features 


FiexOS provides comprehensive facilities for process, file, console, and 
device management. The following list summarizes these facilities: 


@® Process Management 


— FlexOS process execution 

~- Independent, modifiable process environments 

—- Asynchronous events and software interrupt handling 
— Interprocess communication and synchronization 


® Disk System 


PC DOS compatible, with hierarchical file directories | 

Shared file system with file and record locking 

— File system protection based on file and directory ownership 
— User and group file ownership 

Removable media support 


® Real-time processing 


— Support for real-time data acquisition and communications 
- Primitives for real-time process control and other real-time 
applications 


® Console 


—- Escape sequence decoding | 

Standard character and bit- mapped screen interface 

Standard 16- and 8-bit keyboard interfaces including function 

keys, numerical keypad and multikeyed characters 

~ Virtual console management primitives that include window 
support 


® International considerations 


— Support for 16-bit foreign languages 
—- Customization of console messages including country codes 


@ Memory mapping and protection 
® Dynamically loadable device drivers 


® CPU-independent programming 


Disk File System 


The FlexOS disk file system is designed for multiuser and networked 
microcomputer systems. Hierarchical, shared disk files allow for the 
large, shared data bases commonly used with professional work 
Stations. The record and file locking mechanisms, along with security 
through ownership, allow integrity and protection of data. 


FlexOS’s disk file system is designed to protect against file destruction 
from power interruptions or accidental system resets. A utility ts 
provided that reconstructs file directory entries and allocation tables 
from the data area of the disk. 


The FlexOS file system distinguishes removable from permanent media 
and recognizes removable media that have open door interrupts. 


Real-time Kernel 


The kernel provides multiuser and multitasking environments that allow 
both real-time control applications and integrated office environments 
on the same CPU. 


The Programmer's Guide, User’s Guide, and System Guide are generic 
in that they are appropriate for FlexOS systems based on any 
supported microprocessor. Before developing programs, you should 
become familiar with the sections of the FlexOS supplements that 
describe microprocessor-dependent distinctions and differences of 
Operation. In most cases, the points of difference are noted in the 
appropriate sections of this manual. However, not all information is 
cross-referenced. 
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SECTION 1 


te ne = 


Terms, Concepts, and Conventions 


This section defines the terms, concepts, and conventions used in this 
manual and describes the file system characteristics and FlexOS 
architecture. 


1.1 C Language Conventions 


Table 1-1 lists the data-type definitions used to promote C portability 
and reduce compiler differences. 


Table 1-1. Standard Data-type Definitions 


Data Type Definition 
BYTE Signed 8-bit value 
BOOLEAN Byte with one of two values: true/false 
WORD Signed, 16-bit value 
UWORD Unsigned 16-bit value 
LONG Signed 32-bit value 
STRUCT Named sequence (structure) of variables 


1.2 Supervisor Calls 


The functions performed by FlexOS are referred to as Supervisor calls 
(SVCs). SVCs provide file, console, event, process control, and device 
I/O and management services. Table 1-2 lists the SVCs according to 
their .purpose (asterisks indicate those SVCs that can be called 
asynchronously). 


1.2 Supervisor Calls FlexOS Programmer's Guide 


Table 1-2. Supervisor Call Summary 


Purpose Call Action 


File Management 


Console ‘Management 


DEFINE Define logical name for a path 
CREATE Create a file 
DELETE Delete a file 
OPEN Open a disk file 
CLOSE Close a disk file 
READ* Read from a file 

~ WRITE* Write to a file 
SEEK Modify or obtain current file pointer 
LOCK* Lock/Unlock an area of a disk file 
RENAME Rename or move a file 


Obtain keyboard and mouse ownership 


KCTRL 

ORDER Order windows on parent screen 

XLAT Specify keystroke translation 

GIVE Give keyboard and mouse to child proces 
COPY Copy one screen rectangle to another 
ALTER Alter a screen rectangle 

RWAIT* Wait for mouse to enter/leave a rectangle 
BWAIT Wait for mouse button state change 


Event Management 


CANCEL Cancel asynchronous events 

WAIT Wait for multiple events 

STATUS Get status of asynchronous events 
RETURN Get return code of completed event 


FlexOS Programmer’s Guide 


1.2 Supervisor Calls 


Table 1-2. (Continued) 


Purpose Call 


Action 


Real Time and Process Management 


TIMER* 
ABORT* 
COMMAND* 
EXCEPTION 
MALLOC 
MFREE 
EXIT 
ENABLE 
DISABLE 
SWIRET 
CONTROL* 
OVERLAY 


Device Management 


SPECIAL* 
DEVLOCK 
INSTALL 


Table Management 
GET 


SET 
LOOKUP 


Set and wait for timer interrupt 
Abort specified process 

Perform command 

Set software interrupts on exceptions 
Allocate memory to heap 

Free memory from heap 
Terminate with return code 
Enable software interrupts 
Disable software interrupts 
Return from software interrupt 
Control a process for debugging 
Load overlay from command file 


Perform special device function 
Lock or unlock device for user/group 
Install, replace and associate drivers 


Get a table 
Set table values 
Scan and retrieve tables 


* Your program can call these SVCs asynchronously. 


Table 1-3 lists the SVCs by their number. 
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Table 1-3. Supervisor Calls by Number 


Number Call Number Call 
0 F GET 21 Reserved 
1 F_SET 22 F_GIVE 
2 F_LOOKUP 23 Reserved 
3 F_CREATE 24 F_TIMER 
4 F_DELETE 25 F_EXIT 
5 F_OPEN 26 F_ABORT 
6 F_CLOSE 27 F_CANCEL 
7 F_READ 28 F_WAIT 
8 F_WRITE 29 F_ STATUS 
9 F_SPECIAL 30 F_RETURN 
10 F_RENAME 31 F_EXCEPTION 
11 F_DEFINE 32 F_ENABLE 
12 F_DEVLOCK 33 F DISABLE 
13 F_INSTALL 34 F_SWIRET 
14 F_LOCK 35 F_MALLOC 
15 F_COPY 36 F_MFREE 
16 F_ALTER 37 F_OVERLAY 
17 F_XLAT 38 F_ COMMAND 
18 Reserved 39 F_ CONTROL 
19 F_KCTRL 40 Reserved 
20 F_ORDER 41 F_SEEK 


1.2.1 Calling Conventions 


FlexOS Supervisor calls are made by invoking the FlexOS entry point. 
The entry point takes two arguments and returns a value, as follows: 


Arguments: a SVC 16-bit number 
a parameter block pointer or value, 32-bit 
Return: a 32-bit value 
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See the processor-specific supplement for the actual entry mechanism 
and registers used. 


You can call FlexOS independent of a processor by calling the _osif 
function supplied with the operating system. The _osif function has 
two arguments: the SVC number (16 bits) and, depending on the SVC, 
a 32-bit parameter block address or parameter value. The C language 
definition of the __osif function is: 


WORD SVCno; 


LONG parm; 
LONG ret; 
ret = _ _osif(SVCno,parm); 


The __osif function returns the return code in registers, according to 
the convention of the language processor used to create the program. 


You can also call FlexOS independent of the processor by using the 
standard FlexOS SVC library supplied with the language processor 
available for FlexOS. Each of these library functions builds a 
parameter block for the corresponding SVC and calls FlexOS. This 
high-level interface allows the description of FlexOS supervisor calls in 
processor-independent and register convention independent methods. 


1.2.2 Data Structure Representation 


Throughout this manual, data structures are represented as shown in 
Figure 1-1. Listing 1-1 contains the corresponding code lL 
Byte and word order are critical when using these structures. 
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Figure 1-1. Data Structure Diagram 


Listing 1-1. Data Structure Representation 


STRUCT thisstruct 
{ 


BYTE bytel; /* byte offset = 0 i A 
BYTE byte2; /* byte offset = 1 * / 
BYTE byte3; /* byte offset = 2 it f 
BYTE byte4; /* byte offset = 3 * / 
WORD word!; /* byte offset = 4 if 
WORD word2; /* byte offset = 6 ae 4 
LONG long!; /* byte offset = 8 * / 
BYTE byteS; /* byte offset = 12 * / 
BYTE byte6; /* byte offset = 13 * / 
WORD word3; /* byte offset = 14 * / 
); /* length = 16 */ 


1.2.3 Synchronous and Asynchronous SVCs 


All SVCs have a synchronous form. This means the call does not 
return until the operating system completes the event--for example, 
reads a record from the disk, writes a string to the console, or opens 
a file. Some SVCs also have an asynchronous form. These calls 
return a value immediately which uniquely identifies the event 
requested. Program operation can then proceed independently of the 
event. 


Synchronous and asynchronous SVCs take the following forms: 
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ret = s_funcname(parm1,parm2.....parmN); 
emask = e_funcname(swi,parm1,parm2....,parmN); 


SVC names starting with “s_” are synchronous SVCs. The ret value is 
the completion code for the event. 


SVC names starting with “e__” are asynchronous. The emask value is 
the event mask which uniquely identifies the event. The completion 
code for asynchronous calls is acquired with the RETURN SVC. 


The contents of the parameter block block built from an SVC call are 
different, depending on the SVC. 


The individual parameters are always provided in the form shown in 
Figure 1-2. The largest parameter block is 28 bytes long. 


- SOfiware inierrupi address 


parm1 — id (fnum, pid, name, etc.) 


Figure 1-2. SVC Parameter Block 


The Supervisor checks the mode to determine if the SVC is 
synchronous or asynchronous. A mode value of O indicates a 
synchronous SVC; a mode value of 1 indicates an asynchronous SVC. 
A parameter error is returned if the mode specified is not 0 or 1. The 
option and flags values select options unique to each SVC. 
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The software interrupt address is a pointer to an optional software 
interrupt routine available with asynchronous SVCs. FlexOS forces the 
calling process to jump to this routine when the asynchronous event 
completes. 


The ID parameter uniquely identifies the object of the call. For 
example, for a WRITE call the object is a disk file, console, printer, or 
other peripheral device. The ID value in this case is a 32-bit file 
number. 


The buffer is used to store data for transfer to or from the object. 
FlexOS checks the address and size values to ensure there are no 
memory boundary violations. 


Many fields are marked with a 0 (zero) in the individual SVC calls. 
These fields must be set to zero to be compatible with future releases 
of FlexOS. An error is returned if they are not zero. 


1.2.4 Return Codes 


The return code for synchronous and asynchronous SVCs is always a 
LONG value (32 bits). A zero or positive value (high order bit is off) 
indicates a successful operation. SVCs not returning any particular 
value, such as a file number or a process ID, return a NULL (0) value to 
indicate success. For synchronous SVCs, the return value is the 
completion code. For asynchronous SVCs, the return value is the 
event mask, not the results of the operation. 


A negative return code (high order bit is on) for synchronous and 
asynchronous SVCs indicates that an error occurred. The high order 
word contains the module or device code and the low order word 
contains the error type code. See Appendix B for the error code 
descriptions. These codes also apply to the asynchronous call’s 
completion code. 


1.2.5 Asynchronous Supervisor Calls 


Asynchronous Supervisor calls allow a program to process multiple 
events simultaneously. Table 1-4 lists the Supervisor calls with 
asynchronous forms. 
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Table 1-4. Asynchronous SVCs 


SVC Purpose 

READ* Read from a file. 

WRITE* Write to a file. 

LOCK Lock/unlock an area of a disk file. 
TIMER Wait for a time period to expire. 
COMMAND Create a process. 

SPECIAL Perform a special device function. 
CONTROL Control a process with another process. 
ABORT Wait for a process to terminate. 

BWAIT Wait for a mouse button state to occur. 
RWAIT Wait for the mouse to enter or exit a region. 


= You cannot read or write a disk file asynchronously. You can 
Only use asynchronous READ and WRITE on console files, pipes, 
printers, and designated special devices. 


Each process can have up to 31 on-going events; each identified by a 
single bit set in the event mask. The event mask is relevant to the 
following SVCs: 


@® WAIT to synchronize on one or more asynchronous events 
® RETURN to acquire an event's completion code 

@ STATUS to indicate completed events 

@ CANCEL to cancel an event 


FlexOS provides two mechanisms sensitive to event completion. You 
Can suspend program execution until an event or one of several 
events completes or you can execute the software interrupt routine 
(swi) when the event completes. 


Waiting on Events 


Use the WAIT SVC to synchronize program operation on_ the 
completion of an event. : 
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The event or events to wait on are specified in the WAIT argument 
and the call returns when any of the specified events completes. The 
event completed is indicated in the return code. While the process is 
waiting, it is removed from the dispatcher’s ready list and minimizes 
the CPU load. 


To get the completion code for an asynchronous event, use the 
RETURN SVC. RETURN use is limited to asynchronous events that do 
not have a software interrupt (swi). (The completion code is passed to 
the software interrupt and hence is not available to the process.) For 
asynchronous events without a swi, use the WAIT return code as 
RETURN’s event mask. The event mask bit is not reset until RETURN 
has been called. 


The STATUS SVC is also useful to determine completed events. 
STATUS places a heavy burden on the CPU and excessive use impacts 
program performance. You specify the events you want considered in 
STATUS’s argument, and the call ‘returns with the bit of all completed 
events set. 


Interrupting upon Event Completion 


Each asynchronous SVC allows a pointer to a swi so program code 
can be executed asynchronously when an event occurs. When the 
event completes, FlexOS preserves the stack pointers and proceeds 
with the swi. 


Two values are passed to the swi, the completed event’s mask and its 
completion code. Both are LONG values. A swi has the following C 
form: 


swi_routine(emask,compcode) ; 
LONG emask;/*mask of completed event*/ 
LONG compcode;/*event’s completion code*/ 


{ 


/*interrupt routine*/ 


s_swiret(OL);/*swi exit call--return to main program*/ 


) 


FlexOS clears the event mask when the swi is called; do not call 
RETURN to reset the bit. 
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You must use the SWIRET SVC to exit the swi. It gives you two 
options: return to the program at the point of interruption or assume 
the process identity from the main program. For both options the 
stack pointer is restored to its condition when the program was 
interrupted. | 


When you have the swi assume the process identity, you can force a 
return to the main program or not return at all. If you force the return 
to the main program, the stack condition is unknown. Consider the use 
of a routine that returns the stack to a known place and jump to this 
routine from the swi. 


When you have the swi assume the process identity, use EXIT to 
terminate the process. Do not call EXIT until after you have called 
SWIRET, however. 


Note: The asynchronous form of ABORT is typically used as a 
mechanism to preserve a process when it is user-aborted. For 
example, consider a menu-driven program where the user enters a 
control-C to abort a menu-selection. To trap the control-C and return 
to a menu within the program rather than the operating system, you 
wouid use the asynchronous ABORT and a swi io force the return to 
the program. To abort the menu program entirely, the user would have 
to enter two control-Cs. 


To establish critical regions where a swi cannot interrupt program 
execution, use the DISABLE SVC. No swi is executed while DISABLE is 
active, however, FlexOS does log the completion of asynchronous 
events during this time. Use the ENABLE SVC to end the DISABLE 
mode. All event swis impeded while DISABLE was active are executed 
after ENABLE is called. 


1.3 File Specifications 


A file is a logical construct applicable to the range of devices and 
functional units managed by FlexOS. FlexOS uses files to store or 
display information (disk files, pipes, console files, device files), get 
data input (keyboard and device files), and control access (zero length 


pipes). 
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Every file is specified by a path. A path consists of the following 
elements: | 


node:: network node name 
device: logical device name 

\ root directory 
directory\: subdirectory name 
filename file name and extension 


These elements are always entered in the following sequence: 
node::device:\directory\...directory\filename 


If you do not specify a node, device, or directory, the current disk 
directory is assumed. 


The node and device names can be one to eight alphanumeric 
characters. A directory name can have one to eight alphanumeric 
Characters and always has the DIR extension. File names consist of a 
one to eight alphanumeric character name and an optional one to 
three alphanumeric character extension. You cannot have a NULL file 
name. The complete specification cannot exceed 127 characters. 


Directories are distinguished from files in a path specification by either 
backslash (\) or slash (/). FlexOS recognizes the _ following 
abbreviations: 


/ means 'the current directory 
./ means the parent directory 
// means the root directory of the specified device 


Although ./, ./, and // are most useful at the user interface level, the 
FlexOS logical name substitution means these abbreviations can also 
be useful at the programmatic level as well. Note that // ignores 
whatever directory specification preceded the // and specifies the root 
directory on the specified device or, if no device was specified, the 
default device. 


Paths are also used to identify pipe files, console files, and devices. 
The following are examples of path specifications. 
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remote disk file Svri:hd:\dir\FILE.EXT full path 
disk file hd1:/mydir/file.typ device, directory, and file 
pipe piz:mypipe 
virtual console conl:vc002/console screen and keyboard for 
virtual console #2 

device mydevice: 
abbreviations m:a/b\././../x means m:a/x 

m:a/b//c/d means m:c/d 


1.3.1 Uppercase Versus Lowercase Names 


File names can consist of uppercase and/or lowercase characters. 
Name matching is conducted according to the following rules. The 
rules are summarized in Table 1-5. 


® The Disk Resource Manager accepts two types of disk media, 
uppercase media (default) and case sensitive media. You make 
the selection in the disk label. All file names on uppercase media 
are converted to uppercase. On case sensitive media, the Disk 
Resource Manager either converts names to lowercase or leaves 
them as is, depending on the force case flag in the SVC. 


@® Device names are always lowercase and are searched in force 
lowercase mode. This way, an uppercase or lowercase name will 
match a device name. 


@ The DEFINE SVC forces logical names to lowercase but leaves the 
substitution string as_ is. All logical names are forced to 
lowercase when the define tables are searched, but left as is if no 
substitution occurs. 


® Programs using FlexOS’s SVCs can choose between force case or 
not. 
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Table 1-5. Rules for Forcing Name Case 


Default Cases Forced 

Device Case Supported Case 
Disk Upper-only Upper-only Upper 
Mixed Lower 

Pipe Mixed Mixed Lower 
Console Lower-only lower-only Lower 


Miscellaneous Lower-only Lower-only Lower 


1.3.2 Wildcards 


Wildcard characters are available for use with the FlexOS LOOKUP SVC. 
This supervisor call is a scanning tool that searches tables by type and 
extracts items matching the name specification in the LOOKUP call. 
Where there is a match, LOOKUP puts all or part of the table into a 
buffer. The Table 1-6 lists the wildcard characters. 


Table 1-6. Wildcards 


Wildcard Meaning 


Matches any number of characters, 0 or more 
Matches any single character 
. Finds names that do not match the wildcard name 


The * and ? characters can be freely intermixed with characters that 
must be in the item names. The “~ must be the first character of the 
wildcard name. The following examples illustrate the use of wildcard 
characters. 


FlexOS Programmer's Guide 1.3 File Specifications 


Suppose the following set of names exists for a table type: 


a ab abc bac bb bc Cc 
The following wildcard names would specify the indicated Set: 

" a,ab,abc,bac,bb,bc,c (all files) 

"CO. 4 abc,bac,bc,c (all files ending with c) 

eal cn a,ab,bb (all files not ending with c) 

2b ab,bb (all files with a 2 character name ending with b) 

a* a,ab,abc (all files starting with a) 

*p* ab,abc,bac,bb,bc (all files with b anywhere) 

? a,c (all files with a 1 character name) 

tia 0 ab,abc,bb (all files with b anywhere after 1 character) 

*b? abc,bb,bc (all files with b as next-to-last character) 


You can have logical name translation with LOOKUP and use paths in 
your LOOKUP name specification. In path specifications, wildcards can 
only be used in the last element of path. The following examples 
demonstrate valid and invalid uses of wildcards in LOOKUP name 
specifications. 


Specification Explanation 

hd:/B1/GL*.* Valid: Returns the table for all files in directory B1 
on device hd: that begin with GL. 

pi: * mx\input Invalid: The wildcard cannot be used if the file is 
not at the end of the specification. 

hd?:/ Invalid: The wildcard cannot be in the device name 
if there are subsequent directory or file references. 

hd?: Valid: Returns the table for all devices beginning 
with hd. 
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1.3.3 Reserved Names 


Table 1-7 lists file names reserved by FlexOS. The BOOTINIT script 
initially defines default: in the process logical name table and defines 
system: and boot: in the system logical name table. 


Name 
stdin 
stdout 
stderr . 
stdcmd 
prn: 


default: 


system: 


boot: 


Table 1-7. Reserved File Names 


Definition 

The standard input file. 

The standard output file. 

The standard error file. 

Reserved for system use. 

The system list (print spooler) device. 


The process’s current directory: FlexOS expands a NULL 
path to the path associated with default:. A path 
consisting of filename alone is expanded to begin with 
default:. 


The process's system directory: The system directory is 
intended as the location to store shared program and data 
files. FlexOS searches it after any unsuccessful attempt to 
find a match in the default: directory when the path 
specification consists of a file name alone. Files in the 
system: directory must have the system attribute set to be 
loaded in this manner. 


The system boot directory: Device drivers are typically 
located in the boot directory. 


1.3.4 Logical Name Substitution 


FlexOS contains a logical name preprocessor which allows paths to be 
represented by a single logical name. FlexOS checks the first item in a 
path specification against a logical name table and substitutes the 
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replacement string when a match is found. An item is defined as a 
character string delimited. by a NULL, space, tab, or colon. For example, 
if you define home: to be the string 


floppy 1:dir1/dir2/ 


then the path specification home:datafile is expanded to: 


floppy 1:dir1/dir2/datafile 


After the replacement string has been inserted into the original path 
specification, FlexOS checks the first item again for a replacement 
string. This loop continues until no replacement is found. The complete 
file specification after all substitution has been performed cannot 
exceed 127 characters. 


If the file datafile in this example is a logical name, FlexOS does not 
search for the replacement string because it is not the first item in the 
path specification. 


FlexOS maintains a_ single, system-wide logical name_ table--the 
SYSDEF table--and separate logical name tables for each process--the 
PROCDEF tables. FlexOS cross-references the logical names in the 
PROCDEF table first and then the SYSDEF table. You make changes to 
both tables with the DEFINE SVC; however, only privileged users can 
make changes to the SYSDEF table. You can assign logical names for 
complete or partial paths. 


When a process creates another process, the new process, called the 
child, inherits a copy of its parent's local process logical name table. 
Any changes the child process makes affect its table only. The parent's 
table is not modified. This is how the logical names replacements for 
the standard files are passed from parent to child processes. 


1.4 File Access 


FlexOS monitors file access for four types of privileges--read, write, 
delete/set, and execute-—and three types of users--owner, group, and 
world. For disk files, access is monitored only when disk security is 
enabled. (See the description of the disk label in Section 2.4.1 for the 
description of disk security.) Before you can read from or write to a 
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file, you must open it. In your open call, you select which privileges 
(read and/or write) you require and specify an access mode. The 
access privileges available to you depend upon your user and group ID 
numbers. 


When the open is successful, FlexOS returns a 32-bit file number. You 
subsequently access the file by its number. FlexOS keeps all file 
numbers in a global table of open files and uses them to dispatch 
requests to the proper resource manager. The number is disassociated 
from the file when you close it. 


1.4.1 Standard File Numbers 


FlexOS reserves four file numbers for reference to the standard files. 
Table 1-8 lists these file numbers by their reserved names. 


Table 1-8. Standard File Numbers and Names 


File Number Name Description 
0 stdin standard input file 
1 stdout standard output file 
2 stderr standard error file 
3 overlay overlay file 


Note: The overlay file is the command file from which the program 
was loaded. This file is left open when an indication of overlays exists. 


These numbers are not the actual file numbers of your standard input, 
output, error, and overlay files. FlexOS translates these numbers into 
the actual file numbers. The definition of the standard to actual file 
numbers is made by the shell or window manager program. Should 
you need the actual file number; you can get them from the ENVIRON 
table. 


The COMMAND SVC opens stdin, stdout, and stderr. These names are 
inherited from the parent process which called the COMMAND SVC. 
The standard input file is opened for read access in shared file pointer 
mode; the standard output and the standard error files are opened for 
write access in shared file pointer mode. 
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1.4.2 Access Privileges 


There are four access privileges: read (R) allows the process to read 
from the file; write (W) allows the process to write to the file; execute 
(E) allows the process to run the program; and delete (D) allows the 
process to delete the file and set values in the file’s table. 


Access privileges are assigned on a owner, group, and world basis 
when the file is created. Which access privileges are available to a 
given process is determined by comparing its user and group 
identification numbers against the file creator's. At log in, FlexOS reads 
the user’s ID numbers from the USER.TAB file. The comparison is made 
when the user attempts to open, execute, or delete the file. If both 
numbers match (indicating the user is the file owner), FlexOS allows 
the user the access privileges established for the owner. If there is a 
match on the group ID only, FlexOS allows only the group-level access 
privileges. If neither match or the user IDs match but the group IDs do 
not, only world-level privileges are available. | 


User, group, and world categories are independent and do not have to 
provide diminishing levels of access. For example, you can set the 
world level to have complete rights over a file, while the group ievei 
can only write to the file and the owner can only read the file. The 
file owner and superuser can always change the attributes of the file, 
regardless of the security word. 


The privileges available for owner, group, or world access are kept in 
the file’s File Security Word. The File Security Word is a 2-byte bit- 
map of the access privileges by level as shown in Figure 1-3. The 
values are set in the CREATE call. Only disk and pipe files and 
directories have a File Security Word. Console file access privileges 
are determined by the mode. 


15 14 13 12 1110 9 8 7 6 5 4 3 2 1 = 0 


| ~— Reserved—» | <— WORLD —» |<— GROUP —» | <— OWNER —» 


Figure 1-3. File Security Word 
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The execute and delete privileges are determined when the process 
attempts to run or erase the file. You do not need to open the file for 
either operation. You can, however, delete a file once it is open. The 
delete is not performed until the last close is performed on the file. 


You select the process’s read and/or privileges in bits 2 and 3 in the 
OPEN SVC’s flags. If the privileges requested are available in the File 
Security Word, the resource manager checks them against the file’s 
current access modes (see below). If the privilege is available given 
existing modes, the file is opened and the file number returned. 


When a requested privilege is not available, the OPEN succeeds or fails 
depending on the value of the Reduced Access flag in the OPEN call. 
The access level granted is derived by ANDing the privileges requested 
with those in the File Security Word. For example, if the requested 
OPEN access rights are RW and the File Security Word access rights 
are RDE, then the reduced access right is R--the only common access 
privilege. The resource manager determines if that privilege is 
available given any current access modes before opening the file and 
returning the file number. If none of the requested rights match, then | 
an access violation error code is returned and the file is not opened. 


1.4.3 Access Modes 


FlexOS provides a set of access modes which determine whether or 
not and, if so, how open files are shared. These modes are selected in 
the OPEN flags word and consist of the following: 


@® EX: exclusive access by calling process 
@ AR: allow reads by other processes 
~@ ARW: allow reads and writes by other processes 


The default mode is exclusive access, where the calling process 
prevents any other process from sharing the file. Exclusive access to a 
file is denied if another process has the file open. 


lf a process tries to open a file with write privilege and another file 
has the file open in (AR) mode, then the new open is denied and an 
error is returned. | 


ARW mode has two options: shared or unique file pointer. The shared 
file pointer mode is only available to processes with the same family 
ID, and all processes in the family must specify this mode. 
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For processes outside of the family, the file appears in exclusive mode. 
There are no such restrictions when the unique file pointer option is 
selected. 


1.4.4 File Pointers 


FlexOS supports both sequential and random access to pipes and disk 
files. Sequential file access is supported by a file pointer. File reads 
and writes increment the pointer so you need not constantly calculate 
your position within the file. Random file access is supported through 
the use of offsets in the READ and WRITE supervisor calls. The offset 
can be specified relative to the file pointer, the beginning of the file, or 
the end of the file. 


The file pointer is initialized to 0 when you create or open the file. 
Subsequent reads and writes move the file pointer to the byte position 
of the next sequential location. For example, if a new file is created 
and then 12 bytes are written, the file pointer would be pointing at the 
13th byte (essentially the EOF marker). 


Separate processes sharing access to the same file can share the 
same file pointer or can have separate ones. File pointer sharing is 
limited to processes with the same family identification number (FID). 
When the pointer is shared, READ or WRITES by any process update 
the file pointer. Use the SEEK SVC to determine the file pointer’s 
location. SEEK can also be used to set the pointer’s location. 


Random access on printer, console, and other serial files produces 
results that are device dependent. Consequently, file pointers are not 
maintained on these types of devices but rather assume an offset of 0 
independent of the actual request. 


1.5 Deleting Files 


Files are deleted by name with the DELETE SVC. Unless the disk 
security has been enabled or the file has the read-only attribute, there 
is nothing to prevent the calling process from erasing the file. A file 
Cannot be erased when it is set read-only. When file security is 
enabled and the file has not been opened, the calling process must 
have the delete privilege. If the process has the file opened, it must 
have either write or delete privilege. 
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FlexOS does not immediately erase an open file when you try to delete 
it. Instead, FlexOS returns success to the DELETE call but marks the 
file as temporary. FlexOS leaves files marked temporary available until 
the last close is performed. At this point, the file is deleted. 


You can automatically delete files by setting one of two flags when 
you create the file. One CREATE flag designates the file as temporary 
or permanent. Temporary means the file is deleted after the last open 
is closed; permanent means the file remains after the last close. The 
other CREATE flag deletes a file if it has the same name as the file 
you are creating. (Alternatively, you can have CREATE return an error if 
it finds a file with the same name.) 


1.6 Basic Terms 


Table 1-9 defines the special terms used in this manual. 


Table 1-9. FlexOS Operating System Terms 


Term Meaning 
Buffer Address of buffer: Many SVCs require buffers for either !/O 


or information. ‘Buffers must be within the logical address 
range of the calling process. FlexOS checks the buffer 
address and size to ensure legal buffers. 


Bufsiz size of buffer (in bytes): The size of the buffer sets the 
SVC’s limit. For instance, the buffer size indicates the 
number of bytes to transfer in the WRITE SVC. The buffer 
size is also used with the buffer address to catch illegal | 
buffer specifications. 


Completion code 
The return code of an asynchronous event. 
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Term 


Event 


Event Mask 


Flags 


Fnum 


Name 


Table 1-9. (Continued) 


Meaning 


Asynchronous operation: When a process issues an 
asynchronous SVC, the requested activity is called an 
event. For example, in an asynchronous write call to a 
printer, the event is the output of the character or string. 
Events can be successful or unsuccessful, the latter 
indicating that the resource manager's or driver's error 
recovery mechanism determined that the action could not 
be completed. A process can have up to 31 ongoing 
events. 


Asynchronous SVC return value: When you _ call an 
asynchronous SVC, a 32-bit value is returned immediately. 
If it is positive (the most significant bit is 0), the value is 
the event mask for that event. If the value is negative, the 
SVC could not be performed. The event mask is a unique 
value in which one of bits 0 to 30 is set to designate the 
event started. You use this value in subsequent calls to 
check event status and to retrieve the event’s completion 


code. 


The flags word in many SVCs offers options that are 
enabled by setting a bit. Not all SVCs have flags. Bit O in 
the SVC descriptions corresponds to the lowest order bit 
and bit 15 the highest. All unused bits must be set to 0. 


File number: SVCs that do I/O require a file number. You 
get the file number from the OPEN and CREATE SVCs. 


File specification address: File specifications are not 
typically entered in an SVC. Instead, you enter the address 
of a NULL terminated string containing the complete 
specification. For all SVCs, the maximum length string is 
128 bytes limiting you to a 127-byte file specification. 
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Term 


OEM 


Option 


Table 1-9. (Continued) 


Meaning 


Original Equipment Manufacturer: In the context of this 
manual, the OEM is the person or company who integrates 
FlexOS with the computer or develops the interface to a 
supplemental piece of hardware such as a plotter or 
communications card. 


SVC options: Several SVCs have, besides the flags, options 
numbered from 1 to 255. Where options are available they 
are shown in the SVC descriptions in Section 7. OEM- 
supplied SPECIAL calls may also have options not 
documented in this manual. Select the option by entering 
the corresponding value in your call or parameter block. 


Privileged user 


Process 


A process with group and user numbers of 0. Group and 
user numbers are established when FlexOS is loaded from 
information in the USER.TAB file 


Program entity: FlexOS provides a multitasking environment 
in’ which multiple processes) can execute program 
instructions independently of each other. Processes are 
uniquely identified by a process identification number and 
are related to other processes through a family idenfication 
number. A process is always in one of three states: 


® running when it has the CPU 
@ ready when it could use the CPU if it had it 
@ blocked when it is waiting for an event to complete 
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Table 1-9. (Continued) 


Term Meaning 


Return code 
~LONG value returned by a Supervisor call (SVC). 


Superuser Synonymous term for a privileged user. 


swi Software Interrupt Routine: Each asynchronous SVC allows 
the optional use of a software interrupt routine (swi) that 
functions similarly to a hardware interrupt routine. When 
the asynchronous SVC completes its operation, the calling 
process is interrupted and control passes to the swi. When 
the swi is finished, it either returns control back to the 
main process where the main process was interrupted or 
becomes the main process. It is not necessary to have a 
swi specified to execute an SVC asynchronously. 


Table FlexOS data structure: FlexOS provides information about 
itself in structures known as Tables. You can examine 
these tables and in many cases control process 
environments by setting values in the tables. FlexOS also 
provides an SVC for scanning and retrieving portions of 
tables. Table 1-10 lists the FlexOS tables. 


1.7. Tables 


You can monitor most aspects of FlexOS operation through its tables. 
Use the GET and LOOKUP SVCs to retrieve the information and the 
SET SVC to modify those table fields that are read/write. Tables are 
assembled by the supervisor when you make the call; they are not 
maintained in system memory. Section 8 contains detailed information 
about FlexOS tables. Table 1-10 lists the tables. 
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Table 1-10. FlexOS Tables 


Table Name Contents 


Supervisor/Kernel 


PROCESS Process information 
ENVIRON Process environment information 
TIMEDATE System time and date 
MEMORY System memory information 
SYSTEM Global system information 
FILNUM Table information for a given file number 
SYSDEF System level defined names 
PROCDEF Process level defined names 
CMDENV Command line entry 
DEVICE information on devices 
PATHNAME Fully-expanded path for given logical name 
Pipe 
PIPE Pipe information 
Disk 
DISK Disk device information 
DISKFILE Disk file information 
Console 
PCONSOLE Physical console information 
VCONSOLE Virtual console information 
CONSOLE Screen and keyboard information 
MOUSE Mouse information 


Miscellaneous Device 
PRINTER Printer device information 
PORT Port device information 
SPECIAL Special device information 
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1.8 FlexOS Functional Components 
The computer system software can be grouped into three categories. 


Figure 1-4 illustrates the three categories and their relationship to 
each other. 


Physical 


Resource 
Managers 


Drivers 


Utilities 


Supervisor 


Sheii VO Ports | 


Window 


| | Keyboard 


Manager 


Figure 1-4. Computer System Software Categories 


The categories are defined as follows: 


@® Program: This group includes the applications run by users to 
perform tasks and various system management _ utilities. 
Background programs which control the user interface such as the 
shell and window manager also fall into this category. 
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® System: This group provides the file system services, process 
scheduling, and data flow mediation. Programs use these services 
on a system call basis. The supervisor receives the functions and 
sends them to the appropriate resource manager for servicing. 


® Physical: The physical functional unit contains the device-specific 
code, called device drivers. The physical functional unit varies for 
each computer system. This unit translates the generic SVCs 
from the resource managers into the device-specific routine for 
execution. 


These divisions illustrate FlexOS’s two interfaces: the program-to- 
system interface and the system-to-physical interface. This manual 
describes how to call the Supervisor and what you get in return. Refer 
to the FlexOS System Guide for detailed information on how the 
system functional unit relates to the physical functional unit. 


1.8.1 The Supervisor and Resource Managers 


The Supervisor receives SVCs from the program units and sends them 
to the appropriate resource manager. File numbering is another of the 
Supervisor's duties. Every time you open a file or device or create a 
file, the Supervisor returns the file number. You use this number to 
access the file, and the Supervisor uses it to send the cali to the 
proper resource manager. 


The resource managers control the access to the physical devices and 
pipes. Table 1-11 lists the resource managers and summarizes their 
tasks. 
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Table 1-11. Resource Managers 


Resource 

Manager Task 

Disk Manages the disk file system for disk drives. 

Console Manages physical and virtual consoles. 

Pipe Manages interprocess communications through FIFO 
(first-in-first-out) memory files called pipes. 

Misc Manages all devices not managed by the other resource 
managers. 

1.8.2 Kernel 


Not shown in Figure 1-4 is: the FlexOS kernel. This proprietary module 
is responsibie for ali process management tasks. This includes process 
creation, state maintenance, and dispatching. The kernel also manages 


process context switching and scheduling and memory allocation. 


Process scheduling is performed on a priority basis. Priority is 
established at program invocation by a number in the range of O to 
255 (see the COMMAND description in Section 7). 200 is the 
recommended priority for user processes. Higher numbers have a 
lower priority; lower numbers have a higher priority. Processes with 
the same priority are scheduled on a round-robin basis. 


End of Section 1 


SECTION 2 


Disk File Management 


This section describes FlexOS’s disk file management tools and the 
fundamental concepts involved in dealing with files. Table 2-1 lists 
the SVCs available for disk device, directory, and file management. 


Table 2-1. Disk Resource Manager 


Disk Disk Disk 
SVC Device Directory File 
CLOSE Y b as Y 
CREATE Y Y Y 
DELETE Y Y Y 
DEVLOCK Y N N 
GET Y Y Y 
LOCK N N Y 
LOOKUP Y 4 ¥ 
OPEN Y Y* Y 
READ Y N Y 
RENAME N Y Y 
SET Y Y Y 
SEEK N N Y 
SPECIAL Y N N 
WRITE Y N Y 


* You open and close a directory file to get and set its DISKFILE 
table only; you do not open it to read from or write to it. 
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2.1 File Access 


Access to files is initiated using the OPEN or CREATE SVC. Use OPEN 
to open an existing file; use CREATE to make and open a new file. 
Both calls require you to specify a file name; both return a 32-bit file 
number. You use the file number for all subsequent file operations. 
The CLOSE SVC disassociates the file number from the file. Use the 
DELETE SVC to remove files. 


Files can be accessed in a byte-oriented manner. Any record in a disk 
file can be accessed at random. The file system maintains a byte level 
end-of-file on disk files. | 


2.2 Disk File Attributes 


Each file in FlexOS has attributes that control access and define 
characteristics. The attributes are initially established by setting the 
ATTRIB word in the DISKFILE tables. Any user with the delete/set 
access privilege can change the ATTRIB word. The Disk Resource 
Manager records this value in the file’s directory entry. Table 2-2 lists 
the attributes. 


Table 2-2. FlexOS Disk File Attributes 


Attribute Meaning 


Read-only The Read-only attribute overrides the access rights that 
are User/Group based. A process cannot delete or write 
to a Read Only file even if it has write and delete 
privileges for the file. 


Hidden Files with the Hidden Attribute ON are not shown in a 
directory listing unless you use a special option. 
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Attribute 


System 


Archive 


Table 2-2. (Continued) 


Meaning 


Files in the system: directory can be opened indirectly 
when the System attribute is ON. Indirectly means, 
“from another directory.” On each open, if a filename is 
given without device or directory specification, the Disk 
Resource Manager first searches the default: directory. 
If the file is not found, the system: directory is searched. 
If the file is found and the System attribute is ON, the 
file is opened. Files with the System Attribute ON are 
not included in a directory listing unless you a Dey 
ask to see them (see LOOKUP in Section 7). 


If the Archive Attribute is OFF, the file has been archived 
since it was created or last modified. It is automatically 
turned ON if the file is modified. Programs performing 
backup functions can turn this attribute OFF to perform 
incremental backups. 


2.3 Disk Media | 


FlexOS disk media have the following characteristics: 


Disk label 


File security 


A root directory entry containing the label name, 
user and group number of the label's creator, and 
mode flags. The mode flags determine if disk 
security is enabled and whether uppercase and 
lowercase or just uppercase file names_ are 
supported. 


A four-byte field in the file’s directory entry 
containing the creator’s user and group number and 
the two-byte File Security Word. Both are set when 
the file is created. 


File record size A two-byte field in the file’s directory entry 


indicating its record size. A record size of zero is 
equivalent to a record size of one byte. 


2-3 


2.3 Disk Media FlexOS Programmer's Guide 


The File Security Word and record size are set when the file is created 
and the disk label is initialized to 0. The label and its options are set 
in the DISK table. 


2.4 Disk File and Directory Security 


File and directory access is controlled by four factors: 


@ The security enable flag value in the disk label. 

® The user and group ID of the calling process. 

® The owner, group, and world access privileges available. 
@ The access privileges requested in the OPEN call. 


The read-only attribute supersedes the access privileges. An error will 
be returned if you attempt to write to, set DISKFILE values of, or delete 
a file with the read-only attribute return. 


2.4.1 Disk Label 


The disk label is created when you set the LAMODE and LABEL fields 
in the DISK table for the first time. The Disk Resource Manager 
completes the remainder of the DISK table’s label fields by adding the 
label maker's user and group IDs and_=e setting the LAFLAG. 
Subsequently, only that user or a superuser can change the label. You 
cannot remove a label after it is created. You can set all fields to 
NULL. 


File security is not enabled on a disk without a label. Once the label 
is established, you enable and disable disk security by setting and 
resetting LAMODE bit 0. When file security is disabled, all processes 
have full (R,W,E,D) access to all files on the disk. When file security is 
enabled, all users except the superuser are monitored for read, write, 
execute, and delete privilege according to their user and group ID. 
The superuser always has full (R,W,E,D) access to files; regardless of 
the File Security Word contents. 


The disk label also determines if the drive supports uppercase only or 
uppercase and/or lowercase file names. 
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2.4.2 User/group IDs and Available Access Privileges 


Before a file is opened, FlexOS grants all processes the minimum 
access privileges. This lets the process lookup the file’s DISKFILE 
table. To execute, read from, write to, or set the file’s attributes, a 
process must have the corresponding privilege. FlexOS qualifies a 
process for read or write privilege when the process attempts to open 
the file. Execute and delete privilege are determined when the process 
attempts to run and delete the file, respectively. 


To determine the access privileges available to a process, FlexOS 
compares the process’s user and group ID against the file creator's 
user and group ID. This indicates whether the process falls into the 
Owner, group, or world category. The privileges set in the file’s File 
Security Word for that category are the only ones available to the 
calling process. 


The privileges given to the calling process are dependent on three 
Other factors: the comparison of the privileges requested to those 
available, whether or not the file has the read-only attribute, and any 
Current access modes. FlexOS compares the privilege requested 
against those specified in the File Security Word. if there is a match, 
FlexOS then determines if the file is read-only. Finally, FlexOS checks 
the file to see if it is open and, if so, the access mode is set. Some 
access modes-~-for example, write exclusive mode--prevent all other 
processes from using the file. Other access modes--for example, read 
exclusive--let other processes open the file but only for the purpose 
of reading. 


FlexOS opens the file and returns the file number, executes the 
program, or deletes the file when the requested privileges are 
available. The function is not performed if the privileges requested do 
not match those available or are not available given the current access 
mode. Processes can acquire reduced access by setting the 
corresponding flag bit in the OPEN call. 


2.4.3 Directory Versus File Access Privileges 


The user and group mechanisms used to qualify users for access to 
files are also used for directory security. However, access privileges 
to directories have a slightly different meaning than they do for files. 
Table 2-3 compares the two meanings. Directory security, like file 
security, is only enabled when the corresponding LAMODE bit is set. 
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Table 2-3. Privilege Definitions for Files and Directories 


Security 

Privilege File Directory 

Read (R) Allows reading Allows LOOKUP 

| from a file operations on files 

in the directory 

Write (W) Allows writing to a Allows file creation 
file plus the privileges and deletion 
listed for delete/set 

Execute (E) Allows a file Allows opening of files 
to be executed in the directory 

Delete/Set (D) Allows renaming, Allows changing 
changing file attributes of 


attributes, or files in directory 
deleting files 


2.4.4 Access Rules and Restrictions 


Read-only file attribute overrides file access privileges set in the File 
Security Word. The following list describes other access restrictions 
for files and directories. Recall that the rules only apply when disk 
security is enabled. 


® To access any file you need execute access in each directory 
specified in the pathname of the file. 


@® To LOOKUP files you must have read access to the last named 
directory in the path. No access is needed of the _ files 
themselves. 


@® The GET SVC requires only a file number; you do not need any 
access privilege to a file’s DISKFILE table. 
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@ The SET SVC requires write access to the directory the file is in, 
as well as delete or write access to the file itself. The file must 
be successfully opened with delete access before SET can be 
called. A file Owner cannot use SET to change file attributes 
without write access to the directory. After obtaining write 
access to a file’s directory, the Owner can always obtain delete 
access to a file, even if is set to R/O. 


@ The DELETE and RENAME SVCs require write access in the 
directory as well as delete or write access for the file. No 
exception is made for the owner of the file. 


@ The COMMAND and OVERLAY SVCs require execute access to the 
file being loaded. Read access in not required. 


@ The CONTROL SVC requires both execute and read access to load 
a file for debugging. | 


@® The READ SVC requires read access to the file. 


@® The WRITE SVC requires write access to the file. 


2.5 Disk File Access Modes 


The FlexOS disk file system divides open modes and the privileges 
allowed with each mode into three categories. 


1. All exclusive opens, with the exception of read/exclusive (R/EX) 
reserve the file for the exclusive use of the calling process. 


2. (R/EX) Opens are treated as read/allowed shared read (R/AR) 
opens in order to allow the shared open of read/only files by 
multiple processes. 


3. Shared read/write opens do not restrict file access by other 
processes. You can restrict record access with the LOCK SVC. 


The first category applies to other processes only. Previous open 
modes set by a process do not delimit its subsequent open modes 
options. Thus, a process with a file opened in read/write exclusive 
mode can open the file again and in any other mode. However, the 
exclusive mode is in force until that open is closed. 
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2.6 Direct Disk Access 
There are two ways to access the disk directly: 


® with the READ and WRITE SVCs 
® with the SPECIAL SVC disk functions 


Both methods require you to open the disk drive before access is 
provided. Use the OPEN SVC for this purpose using the device name 
to select the drive and the OPEN flags to select the access privileges 
and access mode. FlexOS returns the file number number you use in 
your READ, WRITE and SPECIAL calls. Disk Security measures are 
provided to restrict access. 


2.6.1 Disk Device READ and WRITE 


Using the READ and WRITE SVCs requires the process to have read 
and write privilege and the drive to be installed to allow raw reads and 
writes. In your calls, the Disk Resource Manager translates the offset 
specified into a logical record number. (The disk is treated as a serial 
sequence of records starting with the first head, cylinder, and sector 
and ending at the last sector, cylinder, and head.) The buffer size you 
specify must be a multiple of the sector size and all operations must 
be performed on sector boundaries. The information transferred is the 
data portion of the sector only; the sector header is not included. 


2.6.2 SPECIAL Disk Functions 


The SPECIAL disk functions provide the disk format capabilility and 
direct access to any sector of the disk, including the system area, 
using the file system’s head, cylinder, and sector identification scheme. 
Table 2-4 summarizes the SPECIAL functions and the access modes 
required to use them. 


Note: We cannot guarantee the compatibility of the SPECIAL disk 
functions with future releases of Digital Research® operating systems. 
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Table 2-4. SPECIAL Disk Functions 


Function Description 
Q! Read the system area of the disk 
12 Write to the system area of a disk 
2 Format the system area of a disk 
37 Format a track of the disk 
4 Check the media for change or errors 
5 Flush buffer contents to the disk 
6! Read physical record by head, sector, track 
7? Write physical record by head, sector, track 
8° Set drive’s Media Descriptor Block (MDB) 


1 Must open in at least shared read-only mode. 
2 Must open in exclusive mode. 


2.6.3 Disk Drive Open Modes 


Disk device access is subject to the current access modes. You 
specify the mode you require along with the READ and/or WRITE 
privilege in your device OPEN call. FlexOS compares the request 
against the privileges available, any modes in affect, and, when 
write/exclusive mode is requested, the presence of open files by other 
processes. Three open modes are supported for direct disk access: 


@® GET-only 
@® Shared read-only (AR) 
@ Exclusive (EX) 


The GET-only mode. starts when you open the drive without 
requesting any access privileges or modes. Use this mode to make a 
connection to the device. This connection allows you to use GET to 
retrieve the drive’s DISK table and DEVLOCK to lock the device. This 
type of open has no effect on disk usage by other processes until 
DEVLOCK is initiated. 


The shared read-only mode allows the calling process to have read, 
write, and set access. Other processes are limited to read access with 
the SPECIAL read functions, with the READ SVC, and through the disk 
file system. Use DEVLOCK to restrict disk access further. 
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The exclusive mode precludes all access attempts by other processes. 
The calling process can declare read, write, and/or set access. FlexOS 
does not grant exclusive mode while there are open files or existing 
DEVLOCKs on the drive. While the disk is open, no file system 
Operations can be_ performed. All the SPECIAL disk functions 
supported by a device driver can be accessed in this mode if the 
calling process has obtained the required access level. This is the 
only mode that lets you set the disk label. 


NOTE: Superusers get full read, write, and delete access to a disk for 
any mode, DEVLOCK status, or INSTALL option. 


2.6.4 Disk Security INSTALL Options 


Disk security is established in two places: Options selected when the 
disk driver is installed and the options set in the disk label. See 2.4.1 
above for the description of the disk label. 


The installation options offered in the INSTALL SVC follow: 


® Removable or Permanent Device 
® Device raw reads allowed 

@® Device raw writes allowed 

@® Device set allowed 

@® DEVLOCKs allowed 


The device read, write, and set options control the level of direct 
access to the disk supported by the device driver. Disk security 
cannot be guaranteed if the disk driver allows raw reads ind/or writes. 
When a disk is opened as a device, the read, write, and set options 
determine the allowed access level. 


The DEVLOCK option determines whether processes can use the 
DEVLOCK SVC to lock the drive. The DEVLOCK SVC allows a process 
to lock a disk for its exclusive use or the exclusive use of processes in 
the same family. Superusers can use the DEVLOCK SVC regardless of 
this’ option. 


End of Section 2 


SECTION 3 


Console Management 


This section describes how to perform console I/O under FlexOS. The 
presentation has four parts: 


@ The first part describes general characteristics of the console 
system and introduces the supervisor calls and tables used to 
manage it. Also described are the FRAME and RECT data 
Structures and the console file naming conventions. 


@® The second part describes how to use the WRITE, ALTER, COPY, 
and READ SVCs to control the screen and keyboard. 


@ The third part describes how to monitor console input from the 
keyboard and pointing device with the READ, XLAT, RWAIT, and 
BWAIT SVCs. 


® The fourth part describes use of the CREATE, OPEN, KCTRL, GIVE, 
ORDER, SET, and GET SVCs to create and manage virtual consoles 
and windows. 


The 8-bit and 16-bit character sets referenced in this section are 
described in Appendix A. For the list of the country codes mentioned 
below, see Appendix C. 


3.1 Console File System 


A console under FlexOS consists of a keyboard and screen and 
optionally a pointing device. For convenience, the term mouse is used 
to refer to all kinds of pointing devices. 
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The Console Resource Manager controls console I/O on a file-oriented 
basis. A single file can represent the keyboard and screen or you can 
have separate files. With a single file, read and write access are 
independent so that keyboard and screen access privileges and modes 
can be different. Separate files are used to monitor mouse input and 
to represent window borders. 


Other Console Resource Manager features are: 8-bit and 16-bit 
character modes (individually selectable for keyboard and screen), 
escape sequence decoding, keystroke translation, and multiple 
international character sets. All features are turned on or off with the 
SET SVC. 


FlexOS maintains each physical console independently of other 
consoles on the system, so different features and options can be 
selected for each console. The same independence applies to virtual 
consoles. 


The COMMAND or CREATE SVCs open the standard files stdin (file 
number 0), stdout (file number 1), and stderr (file number 2). The files 
are Opened in shared file pointer mode so all processes in the family 
have console access. (See Section 5 for the explanation of process 
families.) The definitions for these logical names are inherited from 
the parent process. The Supervisor always translates file numbers QO, 
1, and 2 to the actual file numbers. 


For applications invoked from the shell, the standard files should 
represent the keyboard and screen. However, these files might be 
defined to be other than console files through redirection. Get the 
FILNUM table for files 0, 1, and 2 to determine the type of device each 
references. 


3.1.1 Console-Related SVCs 


The console-related SVCs provide two types of services: console file 
I/O and virtual console management. The first type are the SVCs you 
use in applications and utilities to control the screen and gather user 
input. Use the second type in window management programs and 
applications to create and control virtual console displays. Table 3-1 
lists the console-related SVCs by type. 
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Table 3-1. Console-Related Supervisor Calls 


SVC Purpose 


Console File |/O 


ALTER Modify a RECT (rectangle) 

COPY Copy a RECT from one FRAME to another 
READ Read from a console file 

WRITE Write to a console file 

XLAT Translate keyboard input 

BWAIT Wait for mouse button state change 
RWAIT Wait for mouse to enter or exit a RECT 


Virtual Console Management 


CLOSE Close a console file 

CREATE Create a virtual console file 

DELETE Delete a virtual console file 

DEFINE Set process's stdin, stdout, and stderr files 

GET ; Get a table 

GIVE Transfer physical keyboard and mouse ownership 
KCTRL Obtain physical keyboard and mouse ownership 
LOOKUP Scan virtual console tables 

OPEN Open a virtual console file 

ORDER Change order of virtual consoles 

SET Change table contents 


3.1.2 Console-Related Tables 


The Console Resource Manager also maintains tables for each 
physical, logical, and virtual console and mouse so applications can 
determine their console environment and, to the extent allowed, 
change it. Table 3-2 lists the tables associated with console 
management and indicates the console characteristics maintained in 
that table. Complete descriptions of the tables and their contents are 
provided in Section 8. 
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Table 3-2. Console-Related Tabies 


Table Name _— Information 


CONSOLE Number of characters in keyboard's type-ahead buffer 
Screen and keyboard modes 
Cursor position 
Number of character rows and columns 
Virtual console number 
Console type 
Physical console name 


ENVIRON Current stdin, stdout, and stderr file numbers 


PROCESS Process’s DEFINEd physical console number 
Process’s virtual console number 


VCONSOLE Window mode 
Virtual console number 
Console type 
View origin reference point on virtual console 
Total character rows and columns in window 
Window position reference point on parent console 
Total rows and columns in virtual console 
Top, bottom, left, and right border sizes 


PCONSOLE Physical device name and identification number 
Current number of virtual consoles 
Number of pixel and/or character rows and columns 
Console type 
FRAME planes supported 
Attribute and extension plane bit maps 
Country code 
Number of function keys 
Number of mouse buttons 
Mouse serial number 
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Table 3-2. (Continued) 


Table Name Information 


Current mouse form position 

Keystate of Alt, Control and Shift keys 
Current state of mouse button 

Mickeys/pixel sensitivity of rows and columns 
Click interval time period 

Height and width of mouse form 

Position of mouse form hotspot 

Mask to mask effect of DATA rectangle 

DATA rectangle to “BLT” to screen | 


3.1.3 Console Screen Model and Data Structures 


The screen is represented by a three-dimensional data structure called 
a FRAME. The FRAME’s height and width are defined in terms of 
Character columns and rows. Each intersection of a row and column 
defines a FRAME character cell. A cell is always one byte. Figure 3-1 
illustrates the FRAME model. 


The FRAME’s depth is defined in terms of planes, each with the same 
dimensions as the FRAME. There are three planes: character, attribute, 
and extension. Each plane consists of either a two-dimensional byte 
array or a single byte used by the Console Resource Manager to set 
all plane bytes. 
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RECT 


Plane O - Characters 
nrow-1— 


FRAME 


Plane 2 - Extension 
Figure 3-1. FRAME Planes with RECT 


Plane Descriptions 


The FRAME planes are defined as follows: 


@® Character Plane (plane OQ): Each byte corresponds to a text 
character space on the screen. The 8-bit character set used in 
this plane is defined on a per country basis. 


® Attribute Plane (plane 1): Each byte defines the foreground color, 
background color, and color intensity and contains a blink flag for 
the corresponding character cell. The attribute plane byte is used 
as shown in Figure 3-2. 
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Bit 765 432 1 


Foreground Color 
Intensity 
Background Color 
Blink 


Figure 3-2. Attribute Plane Byte Format 


@ The three bits in the foreground and background color fields are 
assigned as follows: 


low bit: blue 
middle bit: green 
high bit: red 


Table 3-3 lists the colors corresponding to each 3-bit value in the 
lefthand column. The righthand column shows the foreground 
color resulting when the intensity bit is set. 


Table 3-3. Foreground and Background Colors by Byte Value 


Foreground and Foreground Color with 


Background Colors Intensity Bit Set 

0 - black ; 8 - dark gray 

1 - blue 9 - light blue 

2 - green 10 - light green 

3 - cyan 11 - light cyan 

4 - red 12 - flight red 

5 - magenta 13 - light magenta 
6 - brown 14 - yellow 

7 - light gray 15 - white 
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Set bit 7 to have the character blink. This feature is not available 
if the hardware does not support it. 


@ Extension Plane (plane 2): An OEM-implemented option § that 


provides support for 2-byte characters. Each extension-plane 
byte is formatted as shown in Figure 3-3. 


Bi: 76543 21 0 


Cell Type 

Cell Number 
Reserved 

OEM Extension 


Figure 3-3. Extension Plane Byte Format 


The Cell Type bit is 1 when characters are two cells long. Single 
cell characters are indicated by a 0 in this bit. 


The Cell Number bit indicates if the corresponding character plane 
cell is the first or second cell of a two-cell character. If the value 
is 0, the cell is the first part of the character; if it’s a 1, the cell is 
the second part. This bit is always O for single-cell characters. 


The OEM Extension field is implementation-dependent and defines 
alternate character sets. The Console Resource Manager assumes 
the standard character set when this field is 0. 
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FRAME C Structure 


The FRAME’s C structure is as follows. Figure 3-4 illustrates this 
memory model. 


struct FRAME 
{ 


BYTE *character,*ftattribute, *extension; 
/*Pointers to planes*/ 
WORD nrow,ncol; 
/*Number of character rows and columns*/ 
WORD use; 


/*Plane bit map*/ 
} 


0 1 2 3 
CHARACTER 
ATTRIBUTE 


EXTENSION 


18 = size in bytes 


Figure 3-4. FRAME Data Structure Diagram 
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The FRAME fields are defined as follows: 


character: Address of FRAME’s character plane 
attribute: Address of FRAME’s attribute plane 

extension: Address of FRAME’s extension plane 
nrow: Number of character rows in the FRAME 


ncol: Number of character columns in the FRAME 


use: A bit map indicating plane characteristics as follows: 
Bit 0: 1 - character pointer addresses a two-dimensional array 
O - character pointer addresses a single byte 


Bit 1: 1 - attribute pointer addresses a two-dimensional array 
0 - attribute pointer addresses a single byte 


Bit 2: 1 - extension pointer addresses a two-dimensional array 
0 - extension pointer addresses a single byte 


The FRAME’s use field indicates if the plane consists of a complete 
two-dimensional array or a single byte. When the plane’s bit value is 
0, the Console Resource Manager applies the single byte’s value to all 
bytes in the plane. Otherwise, the full array must be specified. 


A FRAME is defined as either a screen FRAME or a memory FRAME. 
The screen FRAME is the console screen representation contained in 
the console file. You use the ALTER, COPY, or WRITE SVC to modify 
the screen FRAME, and modifications are immediately reflected on-. 
screen. The memory FRAME is a data structure you create in the 
application’s memory space and hence is not limited to modification 
by ALTER, COPY, and WRITE alone. Changes made to the memory 
FRAME are not reflected on-screen until they are COPYed to the 
screen FRAME. 


Screen FRAME dimensions are indicated by the NROW and NCOL 
values in the CONSOLE table (see Figure 3-6). There are no restrictions 
except physical memory restraints limiting the size of a memory 
FRAME. 
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RECT C Structure 


The RECT data structure defines a rectangular region of a FRAME. The 
point of reference is the FRAME coordinates of the region’s upper 
lefthand corner. The region’s width and height are specified within the 
data structure in terms of character rows and columns. The SVCs 
using the RECT structure specify which FRAME planes are included in 
the RECT: Figure 3-5 shows the RECT data structure diagram. The 
corresponding C structure is as follows: 


struct RECT 
( 
WORD row,col,nrow,ncol; 
/* Top left corner FRAME coordinates 
and RECT width and height *¥/ 
) 


Figure 3-5. RECT Structure 


The RECT fields are defined as follows: 


@ row: The row coordinate relative to the FRAME of the rectangle’s 
upper lefthand corner : 


® col: The column coordinate relative to the FRAME of the 
rectangle’s upper lefthand corner 


® nrow: The number of rows (height) in the rectangle 


@® ncol: The number of columns (width) in the rectangle 
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3.2 Controlling the Console 


Console attributes such as screen and keyboard modes, cursor 
location, and the number of character rows and columns are contained 
in the CONSOLE table. You manage the console screen on a FRAME 
basis with the ALTER and COPY SVCs and on a character basis with 
the WRITE SVC. 


3.2.1 Console Attributes 


The CONSOLE table is your reference source for information regarding 
console attributes and conditions. Figure 3-6 illustrates the CONSOLE 
table data structure. To get or set your process’s CONSOLE table, use 
O or 1 or the stdin and stdout file numbers from the ENVIRON table as 
the GET or SET ID value | 


O- 4 2 3 


Figure 3-6. CONSOLE Table 
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SMODE and KMODE set the screen and keyboard modes, respectively. 
CURROW and CURCOL indicate the current cursor location. These 
values are initialized to 0 when the console is created. Set the mode 
options to select 8-bit or 16-bit characters, escape sequence 
decoding, and other features. Set CURROW and CURCOL to change the 
Cursor position. The remainder of the parameters are read-only; their 
values determined by the physical console’ characteristics or 
established when the corresponding virtual console was created. 


3.2.2 Manipulating the Screen 


There are three ways to manipulate the console display: use ALTER to 
change a screen region, use COPY to copy one screen region to 
another, or WRITE to send a character, character string, or escape 
sequence. ALTER and COPY are also useful for character and string 
Output, however, they cannot be used when console output is 
redirected to non-console devices. 


Note: The window border files vcxxx/top, /bottom, /left, and /right are 
a special class of console file-~only COPY and ALTER can be used to 
manipulate their contents. See 3.4 for the description of the border 
files. 


Using ALTER and COPY 


ALTER and COPY work on RECT structures to modify a FRAME. The 
FRAME can be a memory or a screen FRAME. The RECT can specify a 
FRAME region from single cell up to the entire FRAME itself. The 
ALTER form is as follows: 


ret = s alter(flags,fnum,dframe,drect ,alterb); 


Use ALTER’s flags to select the character, attribute, and/or extension 
plane. To modify the screen FRAME, specify the console file number 
in the fnum field and set the dframe value to zero. To modify a 
memory frame, set the fnum value to zero and put the FRAME address 
in the dframe field. (Although 0 is the file number of the stdin file, the 
Console Resource Manager ignores the file reference.) 


ALTER modifies the plane according to the two bytes in corresponding 
planes alterb argument. Alterb is an array of six bytes that determines 
the alteration of the destination frame. 
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Bytes 0, 2, and 4 in alterb are ANDed with each cell in, respectively, 
the character, attribute, and extension planes. Bytes 1, 3, and 5 are 
XORed with each cell in the same three planes. 


COPY copies the contents of one rectangle to another. As with ALTER, 
each plane is individually selectable in the flag word. Source and 
destination RECT structures can be on the same or different FRAMEs 
and when on the same FRAME can overlap. The COPY form is as 
follows: . 


ret = s_ copy(flags,fnum,dframe,drect,sframe,srect); 


You distinguish memory from screen FRAMES_ using _ specific 
combinations of fnum, sframe, and dframe. To specify the screen 
FRAME as the destination FRAME, put the console file number in the 
fnum field and set the dframe pointer to zero. To specify the screen 
FRAME as the source, set the sframe pointer to zero and specify the 
file number. To copy from one memory FRAME to another use a fnum 
value of 0 and enter the dframe and sframe addresses. 


The source rectangle is described by the RECT at the srect address 
and the destination region by the RECT at the drect address. 
Rectangles do not have to be the same size. COPY clips the rectangles 
so that the region modified corresponds to the intersection of the 
srect and drect. Figure 3-7 illustrates how the excess is trimmed. 


Source Source 
Rectangle Rectangle 


Destination 
Rectangle and 
only region 
‘modified — 


Destination 
Rectangle 


Region 
Modified 


Figure 3-7. Examples of RECT Clipping 
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Using WRITE 


The WRITE SVC sends the contents of the buffer to the console file 
specified by fnum. Use WRITE to send 8-bit escape sequences, 16-bit 
characters, and character strings to the console file. Each character 
output is placed at the current cursor position and the cursor position 
is updated. The screen scrolls automatically when the bottom line is 
reached. 


The synchronous and asynchronous WRITE forms are as follows: 


nbytes = s write(flags,fnum,buffer,bufsiz,offset); 
emask = e write(swi,flags,fnum,buffer,bufsiz,offset); 


The bufsiz value indicates how many bytes long the buffer is, not the 
number of characters in it. This is important when outputting 16-bit 
characters. Similarly, WRITE’s return value (nbytes above) indicates the 
number of bytes, not characters, written. SMODE bit 1 determines if 
the Console Resource Manager outputs 8- or 16-bit characters. 


Use an offset of zero when writing to a console file. Specify the offset 
relative to the end of file to accommodate redirection to non-console 
files. The flags and option values must be O for console writes. 


The character string can contain displayable and non-displayable 
characters. The latter consist of 8-bit escape sequences, ASCII control 
sequences, and 16-bit character codes. Appendix A lists and describes 
the character sets and escape sequences supported by the Console 
Resource Manager. 


3.3. Getting Console Input 


Applications get console input from two sources: the keyboard and, if 
present, a mouse. The keyboard is accessed by reading stdin. The 
mouse is represented by a _ separate file. Mouse movement is 
automatically relayed to the screen without reading the mouse file. 
You use the mouse file to wait for a button state change--the BWAIT 
SVC--or for mouse form movement into or out of a RECT--the RWAIT 
SVC. The SET and GET SVCs are used to define the mouse form and 
determine its location. 
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3.3.1 Reading the Keyboard 


There are two words in the CONSOLE table relevant to keyboard input: 
TAHEAD and KMODE. TAHEAD indicates how many characters are 
waiting in the type-ahead buffer. The KMODE word provides a variety 
of options including keystroke translation, character echo, 8-bit or 16- 
bit characters, and escape sequence decoding among others. 


The READ SVC gets the characters from the console file’s keyboard 
buffer and puts them in the buffer specified. READ might return fewer 
characters than requested; your program should be written 
accordingly. The READ forms are shown below. There are two 
synchronous forms: one for undelimited reads and one that allows 
delimiters to specify an end of string. 


nbytes = s_ read(flags,fnum,buffer,bufsiz,offset); 
nbytes = s_ rdelim(flags,fnum,buffer,bufsiz,offset,delimiters) ; 
emask = e read(swi,flags,fnum,buffer,bufsiz,offset); 


Use an offset of 0 in your read calls and make it relative to the file 
pointer to accommodate redirection to a non-console file. The bufsiz 
specifies the end of the read event in terms of bytes read. Get the 
CONSOLE table’s TAHEAD value to find out the number of characters 
waiting.to be picked up from the keyboard buffer. 


Delimiters let you set up conditions for terminating the read before the 
buffer is full and editing the character string. Set flag bit 1 to select a 
delimited read and bit 5 to use the editing characters. Use the READ 
return value to find the number of bytes read. Delimiters cannot be 
used with the asynchronous READ and you are limited to a READ 
buffer size of 256 bytes on delimited reads. 


The delimiter specification is an address of a WORD array with two 
components. The first word is a number indicating the number of 
delimiters that follow. The remaining words are the delimiters 
themselves. Set the high order byte in each delimiter to 0 when the 
keyboard is in 8-bit mode. 


The Console Resource Manager provides the line-editing characters 
listed in Table 3-4 when READ flag bit 5 is set. You can change these 
definitions with the XLAT SVC. 
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Table 3-4. Line-Editing Characters | 


Character Action 

LEFT ARROW Moves cursor one character to the left 

RIGHT ARROW + Moves cursor one character to the right 

DELETE Deletes next character 

BACKSPACE Deletes previous character 

CTRL-B Toggles cursor between beginning and end of line 
CTRL-X Erases from cursor to beginning of line 


The Console Resource Manager compares each character read with 
each delimiting and editing character. READ returns with the number of 
bytes read when the buffer is filled or one of the delimiters is 
encountered. Use flag bit to select whether the delimiter is included in 
or excluded from the character string. When character echo is on 
(KMODE bit 5), the cursor is positioned at the beginning of the line just 
edited after a delimited read 


3.3.2 Monitoring the Mouse 


Note: This discussion assumes that the mouse device was installed in 
the CONFIG.SYS configuration script. If it is not, your application ¢ can 
use the INSTALL SVC given the following conditions: 


@ The application must know the drive location and file name of the 
loadable mouse driver program. 


@ The application must have a user and group number of 0. 
The INSTALL SVC is described in Section 7. 


Mouse information and status is maintained in the MOUSE table. 
Figure 3-8 illustrates this data structure. 
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Sa a 


MASK (16 words) 


DATA (16 words) 
84 | 


Figure 3-8. MOUSE Table 


The PCONSOLE table also includes information on the mouse. See 
offset 1BH for the number of mouse buttons and offset 1CH for the 
mouse serial number. The mouse can have up to 16 buttons. 


Mouse movement is automatically read from the device and shown on 
the screen by the mouse driver. Get the ROW and COL values from the 
MOUSE table to determine the mouse location; set these values to 
move the form independently of device input. The HOTROW and 
HOTCOL values set the hotspot--the point of reference within the 
mouse form. You can set these and all other MOUSE table values 
except the PIXROW and PIXCOL. 
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Opening the Mouse File 


The mouse is opened by calling OPEN. In your OPEN call you specify 
the mouse name, the access privileges required, and the access mode. 
The mouse name is vcxxx/mouse where xxx is a decimal number 
indicating the current virtual console number. Get the virtual. console 
number from the VCNUM field in your standard input file’s CONSOLE 
table. (Call GET with an ID value of O to retrieve stdin’s CONSOLE 
table.) For example, if the VCNUM value is 3, your mouse name would 
be vc003/mouse. 


In your OPEN call, specify at least read access privilege. If you need to 
set the MOUSE table, request set access as well. For the access mode 
Specify exclusive mode unless mouse access will be shared by 
multiple processes. In this case, specify shared, shared file pointer 
mode. Access is restricted to processes with the same family ID. 


Your application should close the mouse file when you are done, 
otherwise you cannot close or delete the virtual console. CLOSE flag 
bit 0 has no meaning with respect to the mouse and is ignored. 


Using BWAIT 


Use the BWAIT SVC to monitor button state changes. BWAIT counts 
the number of times a specified mouse button condition occurs within 
a given time period. A button condition is defined by two criteria: 
buttons and their ON or OFF state. 


The BWAIT form is as follows: 


re 


t _bwait(clicks,fnum,mask,state); 
emask 


Ss 
e bwait(swi,clicks,fnum,mask,state) ; 


The fnum value is the file number returned when you OPEN the 
vcxxx/mouse file. The mask and state parameters are 32-bit values 
which define the mouse button condition. 


You select buttons for the mask value by their position on the mouse. 
The rightmost button is represented by the least significant bit in the 
mask; the next button to the left is represented by the next bit, and so 
forth. To select the button, set its corresponding mask bit. 
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You define whether the button selected is to be ON or OFF in the 
state value. The Console Resource Manager looks only at the state bits 
corresponding to the buttons selected in the mask. Set the bit for ON. 


As an example of the use of the mask and state fields, consider a 
two-button mouse. You can have the following button conditions: 


1. The right button is pressed (ON) without concern for the state of 
any other buttons: mask = 1, state = 1. 


i 
- 


2. The right button is pressed while the left button is not: mask 
State = 1. 


3. The left button is pressed while the right button is not: mask = 3, 
State = 2. 


4. The left button is pressed without concern for the state of any 
other buttons: mask = 2, state = 2. 


5. Both buttons are pressed simultaneously: mask = 3, state = 3. 


Use the clicks value to delimit the event by a specific number of 
incidences of the specified button condition. Any number of clicks can 
be specified, including 0. Use a click value of 0 to determine the 
mouse’s current condition. BWAIT returns with a value of 0 when you 
specify 0 clicks and the mouse is in the condition defined in the mask 
and state. 


BWAIT counts button conditions for a limited time period--the CLICK 
time limit specified in the MOUSE table. If the time period expires 
before the BWAIT click count is reached, the event terminates. The 
Console Resource Manager starts the timer upon the first incidence of 
the condition. Consequently, the count returned is always at least one 
except as described above. 


Using RWAIT 


RWAIT establishes an event boundary for the mouse. RWAIT returns 
with the row and column coordinates of the mouse’s hotspot when it 
crosses the boundary. The RWAIT form is as follows: 


position = s_ rwait(flags,fnum,region) ; 
emask = e rwait(swi,flags, fnum, region) ; 
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Set RWAIT flag bit 0 to clip the region to the current window borders. 
Otherwise, the region can include areas not visible on the parent 
screen. Flag bit 1 determines if the event occurs when the form exits 
or enters the region. The other flag bits are not used. 


The region is a RECT structure confined to the calling process’s virtual 
console’s FRAME. The position value returned is 32-bits where the 
high order word indicates the row and the low order word the column. 


3.4 Managing Virtual Consoles 


For applications with multiple processes sharing access to the console 
and keyboard, it is often necessary or convenient to have a separate 
virtual console for each process. The key to these applications is a 
process--the window manager--which creates the virtual consoles, 
sets each window's size and position, and passes keyboard and mouse 
access from one process to another according to a planned transfer 
scheme. (These are basically the same functions as the FlexOS window 
manager supplied with the operating system.) 


The window manager flow chart would include the following FlexOS 
functions; the SVCs used appear in parentheses. 


. Create a virtual console (CREATE). 

. Get the virtual console number (GET). 

. Set the virtual console’s window size and location (SET). 

. Assign the console file to stdin, stdout, and stderr (DEFINE). 

. Define conditions under which keyboard and mouse ownership is 
returned (KCTRL and/or MCTRL). 

6. Invoke shell or application that will use screen (asynchronous 


Oh AaN = 


COMMAND). 

7. Give keyboard and mouse ownership to the new virtual console 
(GIVE). 

8. Read from your keyboard buffer (READ). 

9. Reorder the virtual consoles to put the selected one on top 


(ORDER). 


Steps 1 through 5 are repeated to create each virtual console. You 
have a numerical limit of 255 virtual consoles. 
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3.4.1 Creating the Virtual Consoles and Windows 


To create a virtual console, you must specify the console screen on 
which it is to appear. This is called the parent screen. The virtual 
console created is referred to as a child console. Child consoles 
created on the same parent screen are referred to as sibling consoles. 
There are four rules of virtual console management based on these 
relationships: : 


@® A child console always overlays its parent. 


@® Sibling consoles are “stacked” on the parent in the order of their 
creation until reordered by ORDER. 


@ The ORDER SVC only reorders a “stack” of sibling virtual consoles 
and cannot be used to put a parent on top of a child. 


@® An application always has access to its entire console regardless 
of its virtual console’s position in the stack and the size of its 
window. 


Figure 3-9 illustrates the parent, child, and_ sibling console 
relationships and the three rules. As shown in this figure, you can 
have multiple tiers of virtual consoles. As you change tiers, the 
parent/child relationships change. All virtual consoles on a given level 
are siblings. 
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Figure 3-9. Virtual Console Relationships 


Creating a virtual console requires write access to the parent console. 
The form of the CREATE SVC is: 


fnum = s_ vccreate(flags,fnum,rows,columns,top,bottom,left,right),; 


The flag bits select virtual console characteristics as follows: 


@® Whether the console and border are character- or bit-mapped 
@® Whether or not the parent’s screen dimensions are used. 


® Whether or not to keep the parent console contents in memory 
while the child console exists. 


@® Whether the virtual console is temporary (delete on last CLOSE) or 
permanent (delete only with DELETE). 


For the fnum value, use the file number of the parent screen. 
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You specify the virtual console’s dimensions in the rows and columns 
parameters. These become the ROWS and COLS values in the 
VCONSOLE table. The virtual console size is independent of the parent 
console’s dimensions; you can, for example, create a virtual console 
larger than its parent. The top, bottom, left, and right parameters 
define window borders and are described in below. 


CREATE returns the file number of your new virtual console file and 
automatically opens the file. Use this value as the ID number in your 
GET and SET calls to retrieve and modify the VCONSOLE table. 


Virtual Console File Naming 


The Console Resource Manager automatically names virtual consoles 
when you CREATE them. The name consists of the letters vc followed 
by a three digit decimal number corresponding to the VCNUM value 
from the virtual console’s VCONSOLE table. For example, if the VCNUM 
is 10, the virtual console name is vc010. 


A virtual console is composed of separate files representing the 
console (keyboard and screen), mouse, and window borders. Table 3-5 
lists the names reserved for these files. 


Table 3-5. Virtual Console File Names 


File Name Description 

device: vcxxx/console Keyboard and/or screen file 
vcxxx/left Left border of window file 
vcxxx/right Right border of window file 
vcxxx/bottom Bottom border of window file 
VCxxx/top Top border of window file 
vcxxx/mouse Mouse file 


xxx = VCNUM, zero-padded left 


Use the vcxxx/console file in your DEFINE call to assign the stdin, 
stdout, and stderr files to the virtual console’s console file. 
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Be sure to define the files before you call COMMAND so that the files 
are automatically opened. The remainder of the files must be opened 
explicitly by the process before you can use them. 


Windows 


The term window refers to the view of the virtual console. When you 
create a virtual console, the window dimensions are initialized to O 
making the window a point with no height or width. 


You set window dimensions in the VCONSOLE table’s NROW and NCOL 
parameters. Set the VIEWROW and VIEWCOL parameters to position the 
window on the virtual console screen. Finally, set the POSROW and 
POSCOL parameters to position the window on the parent console’s 
screen. Figure 3-10 illustrates these parameters. 


0,0 0,47 


a) POSROW and POSCOL 
b) VIEWROW and VIEWCOL 
c) NROW and NCOL 


120 


Figure 3-10. Virtual Console Characteristics 
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The VCONSOLE flag bit 1 gives you the option to have the window 
view adjust automatically to keep the cursor on-screen or remain fixed 
on a specific portion of the screen. Other flags determine how and 
when the view changes with respect to the cursor and freeze the 
window borders so you can make comprehensive changes to the 
border files without intermediate states appearing. 


The window borders are contained in the vcxxx/top, /bottom, /left, and 
/right files. The Console Resource Manager creates these files when 
you specify top, bottom, left, and/or right parameters in your CREATE 
call. The top and bottom values set the height of the /top and /bottom 
border files only; the length is determined by the VCONSOLE table’s 
NCOL value. The CREATE left and right values set the width of the /left 
and /right files; the height is set by the VCONSOLE NROW value. 


3.42 Keyboard and Mouse Ownership 


Keyboard and mouse ownership are always passed as a unit and only 
one virtual console can have ownership at a time. The window 
manager controls keyboard/mouse access by passing ownership to 
another virtual console with the GIVE SVC and _ “specifying the 
conditions for its return with KCTRL or MCTRL. The conditions 
specified in KCTRL are keys or ranges of keys. With MCTRL, you 
specify a rectangle as the condition. 


The KCTRL keys and MCTRL rectangles typically serve two purposes. 
First, they indicate that the user wants to change windows. Second, 
they indicate the user’s choice of virtual consoles. When the user 
enters one of the specified window-control keys, that key and all 
subsequent keystrokes: are sent to the parent virtual console’s 
keyboard buffer. If there’s a mouse keyboard entries a significant key 
is pressed or the mouse leaves the rectangle, the key and all 
subsequent keystrokes are sent to the window manager's keyboard 
buffer and mouse movement is updated in the window manager's 
MOUSE table. Use the information to determine which window to put 
on top with your ORDER call. 
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3.4.3 Deleting a Virtual Console 


The virtual console’s window remains on the parent screen until the 
file is closed or overlayed by a sibling virtual console. A partial CLOSE 
flushes the keyboard’s type ahead buffer and, if the echo option 
(CONSOLE table KMODE bit 5) is selected, writes the buffer contents to 
the screen. A full CLOSE closes the file but leaves its contents intact 
unless it is the last close on a temporary console. In this case, the 
virtual console and all temporary files are deleted. 


The Console Resource Manager only lets you delete a virtual console 
if it has no open /console, /mouse, /top, /bottom, /left, and /right files. 
Neither can you delete a virtual console with child consoles. If you try, 
an error message is returned. You can set CREATE flag bit 8 so that 
the virtual console is automatically deleted when the last of its virtual 
consoles is closed. Otherwise, use the DELETE SVC to remove the 
virtual console. 


3.5 FlexOS Window Manager 


WMEX, the window manager program provided with FlexOS, lets the 
user create, delete and switch virtual consoles. It also creates a 
message window you can use to interrupt the user and notify him or 
her that something has happened. You write to a reserved pipe to 
activate the window. When you write to this pipe, the message 
window overlays the current virtual console. You specify in your 
WRITE call to the pipe if a response is necessary. | 


To use the message window, you must open the file “wmessage.” 
WMEX defines this file name to the message window’s input pipe and 
waits for a message to appear there. In your OPEN call, specify the 
write privilege and the shared mode. i 


WMEX requires the display message to be preceded by a header. 
When you write to the pipe, format the contents of your WRITE buffer 
as follows: 
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UWORD msgsiz The total length of the message 
LONG pid The writing process’s process ID 
BOOLEAN rspfig When true, indicates that a user 


response is expected; when false, 
no user response is allowed 
UBYTE rspname[10] Name of the pipe in which WMEX 
should put the user’s response 
(only necessary when rsplfg true) 
UBYTE message The message to be displayed 


The message itself can be 10 lines long. Each line must be terminated 
by a carriage return and line feed. The message is displayed as is. 


If no response to the message is required, set the rspflg byte to false. 
The user enters a carriage return to remove the message window. If 
you want a response, set rspflg to true and give WMEX the pipe name 
to write the message to. 


The response message is limited to one line in length and WMEX 
requires the user to enter a carriage return to terminate it. The 
Carriage return is included in the string written to the pipe. If the 
message can be variable length, use the delimited READ call and 
specify the carriage return as the delimiter. WMEX removes the 
message window when the user enters the carriage return. 


End of Section 3 
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SECTION 4 


Pipe Management 


For two or more processes to communicate, a type of file known as a 
pipe is supported through a special device known as pi:. A file created 
on this device establishes a buffer used for the deposit and withdrawal 
of messages. Conceptually, pipe files have two ends, one to write into 
and the other to read from. Messages are deposited and withdrawn 
on a first in first out basis. Besides the pipe length, there is no limit to 
the number of messages you can store in a pipe at one time. 


This section describes pipe management in the FlexOS operating 
system. Table 4-1 lists the pertinent SVCs. 


Table 4-1. Pipe-related Supervisor Calls 


SVC Purpose 

CLOSE Close a pipe 

CREATE Create and open a pipe 
DELETE Remove a pipe 

GET Retrieve a pipe table 
LOOKUP Scan and retrieve pipe tables 
OPEN Open a pipe 

READ Read from a pipe 

SEEK Set or retrieve file pointer 
WRITE Write to a pipe 


You cannot rename a pipe. 


In all calls requiring a pipe name, you must precede the pipe name 
with the pi: device name or define a logical name that includes the pi: 
reference. Otherwise, the default: device is assumed. 
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4.1 Creating and Deleting Pipes 


Use the CREATE SVC to make a pipe. The CREATE parameters are used 
as follows: 


@® Set the flags to request read, write, or delete privileges and the 
access mode. The privileges have the same meaning for pipes as 
they do for disk files. See 4.2 for the use of access modes with 
pipes. Flag bits 7 and 9 are meaningless with reference to pipes 
and are ignored. | 


@ Put the address of your pipe name in the name field. The name 
itself is limited to eight alphanumeric characters. 


@ Set the record- size parameter to regulate the message blocks. 
For example, if a record size of four is speciied: all pipe 1/O is 
conducted in 4—byte blocks. 


@ Use the File Security Word to set the owner, group, and worid 
access privileges. 


@ Set the size to the pipe buffer length. The size is independent of 
the message length but must be a multiple of the record-size. 


The Pipe Resource Manager maintains a directory of all existing pipes. 
Each directory entry includes the pipe creator’s user and group IDs 
and the File Security Word. The resource manager also makes a PIPE 
table for each pipe. PIPE table contents indicate the values set by the 
CREATE pipe call. Use LOOKUP and GET SVCs to retrieve PIPE tables. 
No special access privilege is required to lookup PIPE tables. However, 
you must have opened the PIPE to get its table. None of the values in 
the PIPE table can be set. 


Use the DELETE SVC to remove a pipe. A CREATE option can be 
selected that automatically deletes a pipe on last close. If the pipe is 
being used solely to communicate between two or more processes for 
the life of the processes, the pipe is deleted automatically from the 
system when the processes terminate. This is because files are 
automatically closed on EXIT or ABORT. 
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4.2 Pipe Access 


Processes must open the pipe before they can read from or write to it. 
When the OPEN call is made, the Pipe Resource Manager compares the 
user and group IDs of the calling process with those in the pipe’s 
directory entry. This determines whether owner, group, or world 
access privileges are available. If both user and group IDs match, 
owner privileges are available; if only group match, group privileges 
are available. If there’s no match, only world privileges are available. 


The OPEN call succeeds when the access privileges requested either 
match or do not exceed the privileges available for the calling 
process’s access level. If more privileges are requested, the OPEN 
succeeds or fails depending on the value of the OPEN call’s reduced 
access flag. When this flag is set, the privileges granted are derived by 
ANDing the requested privileges with those available. Should none of 
the privileges match, the OPEN fails. 


Pipe access privileges are also affected by existing access modes. The 
following rules govern the privileges available: 


@® A process’s open access is never restricted by an open 
connection previously made by the same process. 


® The read and write ends of a pipe are considered separate with 
respect to open restrictions. For example, an exclusive read open 
does not restrict a process from opening a pipe as shared write. 


@® Any exclusive open prevents other access requests to the same 
end. 


-®@ A shared open prevents other exclusive access requests but 
allows other shared requests to the same end. 


@ A shared file pointer request restricts pipe access to processes 
with the same family ID. All processes sharing the pipe must 
select the shared file pointer mode; a process that requests a 
different mode is denied access. For processes outside the family, 
the request functions as an exclusive request. 


A pipe acts differently depending on whether an end is opened 
exclusive or shared mode. If one end of a pipe is opened in exclusive 
mode and then closed, a read or write attempt on the other end 
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results in an end-of-file (EOF) error. This is independent of how the 
other end was opened. If one end of a pipe has either never been 
opened, is currently opened, or the last open was in shared mode, the 
process accessing data through the opposite end waits until the 
Operation is complete. 


If one end of a pipe file is opened in shared mode and subsequently 
closed, FlexOS treats the file as if it were still open on the other end. 
Therefore, any process accessing it waits until the operation is 
complete. Note the distinction between shared mode and shared file 
pointer mode. 


A pipe opened in shared file pointer mode is shared only by those 
processes with the same family ID (FID). After a pipe end opened in 
Shared file pointer mode is closed by all of the processes, processes 
accessing the other end will receive an end of file error. This tells a 
process that the process on the other end of the pipe has either 
closed the file or terminated. 


The use.of modes to restrict access is consistent with spooler-type — 
applications. For example, consider a spooler process which creates a 
pipe reserving for itself exclusive access to the read end. The write 
end is available for shared access by any process. Figure 4-1 
illustrates this configuration. 


spooler Despooler 
Request 
Pee 
peuueeey 
Shared | Exclusive 
Request Write Read 
When no opens, When closed, requesters 
despooler waits get EOF error 


Figure 4-1. Spooler Pipe 
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Processes open and close the write end when they are sending files to 
the spooler. After the write end is closed, the despooler waits until the 
write end is opened by another process. 


If the spooler closes the read end, processes attempting to write to 
the other end get an end of file error. This indicates to the writing 
process that there is no process at the other end that will read its file. 


4.3 Interprocess Communication 


Use the READ SVC to get data from the buffer and the WRITE SVC to 
put data in the buffer. The READ and WRITE flags and parameters are 
used in the same manner for pipes as they are for disk files and the 
file pointer is maintained. As many processes can participate in the 
exchange as you want. 


The amount of data written to and read from the pipe can be 
independent of the pipe size. The following procedures are observed 
when the amount exceeds the size: 


® On writes, the process waits when the pipe is full for another 
process to read data from the other end. The event completes 
when the reading process removes enough to compensate for the 
difference. 


@® On reads, the process waits when the pipe has been drained for 
another process to write data to the other end. The event 
completes when enough data has been written to compensate for 
the difference. 


Pipes are often used to join two or more programs so one program's 
output becomes the input of another. To do this, a parent process 
would perform the following steps. The SVCs called are in parenthesis. 
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1. Create a pipe (CREATE). 
2. Redefine stdin to be the name of the pipe (DEFINE). 


3. Create the receiving process (COMMAND). The child inherits the 
parent's PROCDEF table, including the stdin prefix. 


4. Reset stdin back to the original name (DEFINE) 
5. Redefines stdout to the pipe name (DEFINE). | 


6. Create the source process (COMMAND). This child inherits the 
redefined stdout but, unlike the receiving child, has the original 
stdin. 


When the two processes terminate, the parent process closes the pipe. 
If the parent terminates before the children, the pipe is automatically 
removed when the children terminate. 


4.4 Synchronization and Exclusion 


The Pipe Resource Manager lets you create pipes with a zero-length 
buffer size (bufsiz) for use as a simple semaphore. For semaphore 
pipes, a READ operation obtains the pipe and a WRITE releases it. If 
another process has obtained the pipe previously, the calling process 
waits until a WRITE to that pipe has been performed. WRITE 
Operations, on the other hand, never wait; if the pipe was released 
previously, the call returns without error. 


The process creating the semaphore pipe automatically owns it from 
the start. Although the Pipe Resource Manager keeps a record of who 
read the pipe, a WRITE by any process releases it. The process ID is 
maintained for two other reasons: First, so that a process can Call 
multiple READs on a pipe it already owns and second, so the Pipe 
Resource manager can release pipes owned by a process that has 
terminated. 
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Use a semaphore pipe to regulate access to a resource not managed 
by the operating system. Any time a process wants to use the 
resource, it reads the pipe. If the pipe is already owned by another 
process, the calling process waits until another process releases it 
with WRITE. Upon return from the READ, the process is free to use 
the resource. Upon completion, the process writes to the pipe which 
releases the resource for other processes to use. : 


4.5 Nondestructive READ 


The information stored in a pipe can be previewed using the READ 
SVC by setting flag bit 2. This allows a pipe to be used as a common 
data area among multiple applications. It also allows an application to 
preread a length field or message type field within a message and 
then read the complete message at a later time. 


Note: Nondestructive reads can be dangerous if there are multiple 
readers of a pipe. It is the responsibility of the application to handle 
synchronization of pipe usage when there are multiple processes 
involved. 


End of Section 4 


SECTION 5 


Process Management 


This section describes process creation, memory management, and 


process deletion. Table 5-1 lists the SVCs associated with these 
tasks. 
Table 5-1. Process-related SVCs 

SVC Purpose 

ABORT Terminate a process or wait for a process to terminate 

COMMAND ~ Create a process 

CONTROL  . Run a process under the control of another process 

ENABLE Enable software interrupts 

EXCEPTION Trap error conditions and jump to service routine 

EXiT | Terminate a process with return code 

DISABLE Disable software interrupts 

MALLOC Add memory to heap 

MFREE Release memory from heap 

SWIRET Return from a software interrupt 

TIMER Delay process for specified time period 

OVERLAY Load overlay from a command file 


The presentation belows describes how to use the ABORT, COMMAND, 
MALLOC, and MFREE SVCs. See Section 7 for the descriptions of the 
other SVCs listed in Table 5-1. 


Three supervisor tables are pertinent to process management: the 
CMDENV, ENVIRON and PROCESS tables. 
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® CMDENV contains the command file specification and command 
tail from the process’s spawning COMMAND call. 


@ ENVIRON contains the process's stdin, stdout, stderr, and overlay 
file numbers; user and group numbers; and identification numbers. 
A process’s ENVIRON table contents are inherited from its 
parent's. 


@® PROCESS contains the process’s identification number, user and 
group ids, name, current state, parent ID number, virtual console 
number, and memory allocation. Some PROCESS table values are 
set with the COMMAND SVC and while others are set ~ the 
Supervisor. 


5.1 Process Relationships 


A process executes program instructions independently of other 
processes. A process is constrained by a process environment 
maintained by the operating system. Environment characteristics 
include the process's logical address space (memory), CPU state and 
stack condition, user and group ID, and parent process. FlexOS uses 
these characteristics to manage the proces and protect it from other 
processes. 


Processes are identified by a unique 32-bit process identification 
number--PiD--and a name. The PID is assigned by the kernel when 
the process is created and remains assigned to the process until it 
terminates. The Supervisor splits running time for FlexOS processes on 
a priority basis. The recommended priority for user processes is 200. 
Processes with the same priority are allocated running time on a 
round-robin basis. 


Besides the process ID, processes are also distinguished by a process 
family. identification number--FID. When one process creates another, 
they keep the same FID unless you request a new number. Within a 
family, a process that creates another process is called the parent; the 
process created is called the child. Typically, the FID is used to 
distinguish processes running under different shells. That is, the shell 
is the head of the family. 
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5.2 Running a Program 
Running a program has two steps: 


@® Loading an executable program file from disk into memory 
® Assigning a process to execute the instructions 


You use the COMMAND SVC to perform both steps. The process 
calling COMMAND must have the execute access privilege to the file. 


Note: At the driver level, you can also uSe the PCREATE function to 
create a process. See the FlexOS System Guide for an explanation of 
PCREATE. | 


The COMMAND SVC searches the disk for the command file specified, 
opens it, and loads it into memory. Running a program does not 
require the creation of a new process. COMMAND gives you the 
following options. 


® Run the program as an independent (child) process: This option 
Creates a new process ID for the program. Child processes get 
their own memory allocation and execute FlexOSly with the other 
process. | 


® Run the program as a procedure: This option runs the program 
as a subroutine of the calling process; no new process ID is 
assigned. The calling process's memory — allocation’ is 
supplemented by the new _ program’s specification. When a 
procedure program exits, control is returned to the next 
executable statement in the parent process. You must use the 
synchronous form of COMMAND to use this option. : 


® Chain the program to the current program: This option runs the 
program as a subroutine within the context of the calling process; 
no new process ID is assigned nor memory allocated. However, 
the process never returns to the previous program. The chained 
program's memory requirements overlay the process's existing 
allocation. When the chained program exits, the process 
terminates. You must use the synchronous form of-COMMAND to 
use this option. 
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When you call the synchronous form of COMMAND, the call does not 
return until the program exits or the process is aborted. When you use 
the asynchronous form of COMMAND, the event mask is returned and 
the child's process ID is recorded at the &pid address you specify in 
your COMMAND call. The event completes when the child process 
terminates. 


Unless externally aborted, a process executes the program instructions 
up to and including the EXIT call. When the Supervisor receives the 
EXIT call, it closes all open files belonging to the process and cancels 
any outstanding events. This completes the COMMAND event. For the 
first and third COMMAND options described above, the process ID is 
then released along with the process’s memory; for the second option, 
the process returns to the next instruction in the previous program. — 


5.3 Process Termination 


The synchronous form of ABORT SVC terminates the process specified. 
This terminates the COMMAND event; all files belonging to the process 
are closed, outstanding events cancelled, and memory released. 


The asynchronous form of ABORT is useful as a _ self-preservation 
measure for processes aborted externally. For example, consider the 
user who enters a control-C to terminate his or her program. For 
many applications, it is preferable to return to a previous location in 
the program rather than abort the program entirely. 


To trap the control-C and force the return to a specific location in the 
program, call the asynchronous form of ABORT; use a process ID of 0 
(this indicates current process) and include a software interrupt (swi) 
pointer. In your software interrupt, use the SWIRET option which keeps 
the process ID in the swi and then call a jump instruction to return to 
the program location. 


Remember that the stack is in an unknown condition when you make 
the jump. At the: return point in your program you should include 
instructions to mark the stack frame so it is restored to a known 
condition. 
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5.4 Memory Management 


You use the MALLOC and MFREE SVCs to manipulate a process’s 
memory allocation. Only the heap portion can be modified: MALLOC 
extends the heap space or adds a new heap and MFREE releases 
allocated heap memory back to the kernel for subsequent allocation. 


To add contiguous memory to an existing heap, select MALLOC’s 
expand option. In your MALLOC call you also give a pointer to a buffer 
indicating the minimum and maximum amount of memory and the 
base address of the heap to expand. Get this address from the 
process’s PROCESS table. The kernel adds as much as can be allocated 
within the parameters given and returns the new _ block’s starting 
address and the number of bytes allocated in your buffer. The original 
heap base address and contents are not affected. 


To get a new, independent heap select MALLOC’s allocate option. The 
new memory block may or may not be contiguous with an existing 
heap segment, depending upon current system memory usage. As 
above, you pass a buffer pointer where a minimum and maximum 
amount of memory is specified. You do not need to specify a starting 
address, however. The heap’s base address and its actual size are 
returned in the buffer. When you add a new heap and it is contiguous 
with an existing heap, the existing heap becomes a fixed data area. 


End of Section 5 


SECTION 6 


Miscellaneous Resource Manager 


This section describes the SVCs used for device management through 
the Miscellaneous Resource Manager. All devices except for disk 
drives, consoles, mouses, and network controllers are controlled by the 
Miscellaneous Resource Manager. This includes such devices as 
printers, plotters, modems, and custom, OEM-implemented peripherals. 
The term device is used in this section as a generic expression to 
refer to all miscellaneous devices. Table 6-1 lists the SVCs. 


Table 6-1. Miscellaneous Device Control Supervisor Calls 


SVC Purpose 

CLOSE Close a device 

DEVLOCK Lock device from access by other processes 
GET Retrieve a device table 

SET Set device table values 

OPEN Open a device 

READ Read from a device 

WRITE _ Write to a device 

INSTALL Install the device driver or subdriver 
SPECIAL Send data to or receive data from driver 


6.1 Device Tables 


The Miscellaneous Resource Manager maintains four device-related 
tables. | 


@® DEVICE: Scan the DEVICE table to get the logical port and printer 
names. The Miscellaneous Resource Manager manages all devices 
with type numbers 7xH and 80-FFH. , 
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@ PRINTER: Use this table to get and set printer parameters. You 
cannot get or set a printer’s table until you have opened the 
device. 


@ PORT: Use this table to get and set I/O port parameters. You 
Cannot get or set a port’s table until you have opened it. Ports 
linked to a driver cannot be accessed with GET and SET; use the 
SPECIAL functions instead. 


@® SPECIAL: Devices not adhering to the PRINTER or PORT table 
models have SPECIAL tables. SPECIAL table contents are OEM- 
defined. 


FlexOS reserves the name prn: for the system list device. Unlike stdin, 
Stdout, and stderr, prn: does not have a reserved file number. Your 
program must open the prn: device, write data to it, and then close 
the device. 


Note: The following description of device !/O assumes the device 
driver is already installed. If it is not or if your software must establish 
a driver-to-subdriver link, section 6.3 below reviews device installation. 
See the FlexOS System Guide for additional information on drivers. 


6.2 Device Access 


Unlike files, devices are installed and removed rather than created and 
deleted. Like files, you must open devices to access them. To indicate 
the device, you its name in the OPEN call. The access privileges and 
modes characteristic of disk files and pipes also apply to devices. Like 
pipes and consoles, read and write access privileges are treated 
separately and can be implemented with different modes. 


6.2.1 Opening and Closing 


Use the OPEN SVC to open the device. Set the flags to select the 
access privileges and modes. The privileges and modes supported are 
determined by INSTALL options selected and the device driver itself. 
The Miscellaneous Resource Manager compares the _ privileges 
requested with those available. Set flag bit 7 if you can accept reduced 
access. You must set flag bit 0 if you want to set the table values. 
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Note: The devices with PORT tables cannot be used for data I/O; 
access to these devices is limited to getting and setting PORT table 
values. 


The OPEN call returns the file number used for all subsequent device 
access. The file number is also used as the ID number in GET and SET 
calls and the file number for your CLOSE call. When you close the file, 
the write buffer contents are output to the device. 


After the device is opened, you can get and set table options. Devices 
are process independent; table variables are not initialized or modified 
as processes open and close the device. Thus, the PRINTER table 
typeface mode or PORT table baud rate selected by one process 
remains set for other processes. 


6.2.2 Security 


Security options come in two forms: access modes and device locking. 
The access modes are selected in the OPEN call. If multiple, related 
processes need to share access to the device, set flag bit 6 to shared 
file pointer. Although the file pointer may or may not be meaningful, 
this is the mechanism used to limit device access to those processes 
in the same family. 


The DEVLOCK SVC can also be used to restrict access. This feature is 
only valid if the INSTALL option allowing DEVLOCK was _ selected. 
~DEVLOCK options let you limit access to the process or the process 
family. The lock is removed explicitly using DEVLOCK or implicitly 
when the process terminates. 


6.2.3. Data I/O 


Use the READ and WRITE SVCs to get data from and to the driver. 
The file pointer offset may or may not be meaningful. Although the 
Miscellaneous Resource Manager does not maintain a file pointer, it 
does pass the offset to the device. Consequently, you can use an 
Offset if the device supports random l1/O. The SEEK SVC is not 
supported by the Miscellaneous Resource Manager. However, the 
function not implemented error is not returned if you call it. Instead, a 
zero is returned. (This is done so redirection to a miscellaneous device 
does not cause an error on seeks.) 
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All WRITE flag options are supported. 


All READ flag options except the edited read (flag bit 5) are supported 
by the Miscellaneous Resource Manager. This includes the use of 
delimiters to complete the read event. As with consoles, your program 
should be able to accept fewer characters on a read than requested. 


SPECIAL functions are another way to transfer data to and from a 
device. However, all SPECIAL functions are driver-dependent; there are 
no generic functions. The Miscellaneous Resource Manager acts as a 
conduit for SPECIAL calls and provides no services beyond transferring 
the SPECIAL databuf and parmbuf contents. 


6.3 Device Installation 


Device drivers are installed with the INSTALL SVC. The driver can be 
read from a disk file or replicated from an existing driver. Only 
privileged users can call INSTALL. 


FlexOS supports the concept of subdrivers. This allows a driver unit to 
be independent of specific hardware by accessing the hardware in a 
generic way. For example, multiple units of an RS-232 subdriver can 
be installed and then linked to printer, network, or communications 
drivers. This relieves the driver writer of hardware dependent code and 
provides flexibility when installing add-on or custom peripherals. 


6.3.1 Driver and Subdriver Installation 


Although drivers and subdrivers are usually installed when the system 
is loaded, they can be installed after the installation script has been 
performed as well. (See the CONFIG.SYS description in the FlexOS 
system Guide for description of the installation script.) You can also 
uninstall drivers, disconnect a subdriver from a driver, and link a 
subdriver to a driver dynamically. 


Once a driver-to-subdriver link is established, the subdriver is no 
longer individually accessible; the driver owns. it. When the link ts 
dissolved, the subdriver is available for linking to another driver. The 
Miscellaneous Resource Manager manages subdrivers until they are 
linked to a driver. Then the driver assumes subdriver management 
responsibilities. Subdrivers can themselves have their own subdriver. 
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Note: The subdrivers with PORT tables do not have a standard 
interface to the resource manager. Do not attempt to access these 
drivers directly: 


6.3.2 INSTALL Options 


Drivers and subdrivers are installed with the INSTALL SVC. There are 
four INSTALL options. 


@® Load driver from the disk: Read the driver from the specified disk 
file, load it into the system space, call the initialization routine for 
the first unit, and give it a logical name. 

® Add a unit to an existing driver: Replicate an existing driver in 
system space, initialize the device, and give it a logical name. 

@® Link one driver to another: Make one driver the subdriver of 
another. Both drivers must already be installed. 

@® Uninstall the driver: Remove the device driver and _ release 
subdriver. | 


Each unit installed manages a separate device; for example an RS-232 
port. Multiple units derived from the same driver are distinguished by 
unique names, however, they all share the same code. 


The driver determines the maximum access privileges supported by 
the device and the access modes. The maximum access modes are 
determined when the device is installed. 


You do not use the DELETE SVC to remove a driver. Instead, use 
INSTALL’s uninstall option. Only the device specified is removed; if the 
driver had a subdriver, the subdriver is released and becomes available 
for direct access or linkage with another driver. 


6.4 PORT Table Modification 


PORT table devices cannot be accessed directly; they can only be used 
as subdrivers. You can, however, set PORT table values. There are two 
ways to do this; depending on whether the device has driver or 
subdriver status. To determine the device status, look at the INSTAT 
word in its device table. | 
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A device that is not a subdriver (it as not been linked to another driver 
with INSTALL), can be opened directly. In your OPEN call, request only 
the set access privilege (flag bit 0). Use the file number returned as 
your GET and SET ID. 


Devices that are subdrivers cannot be accessed directly. However, you 
can use SPECIAL functions 13H and 93H to get and set the PORT table 
values. These SPECIAL functions are described after the SPECIAL disk 
functions in Section 7. 


To use the SPECIAL functions, you must know the driver that owns the 
subdriver. The OWNERID value from the subdriver’s DEVICE table is the 
significant 16 bits of the subdriver’s owner's DEVICE table key value. 
Use this value in a LOOKUP call to find the device name. If the owner 
is also a subdriver, repeat this procedure to get the owner. When you 
determine the owner, open the device and use the file number 
returned in your SPECIAL calls. 


End of Section 6 
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Supervisor Call Descriptions 


This section describes the FlexOS SVCs. The descriptions are 
presented alphabetically by SVC name and contain explanations of 
each call’s arguments and return codes. See Section 1 for the 
description of the C and assembler interface conventions used in the 
descriptions. Appendix B lists the error return codes. 


The descriptions also include a general explanation of the function's 
purpose and effect. For specific information regarding when and how 
to use the SVCs, refer to the chapters describing disk, console, pipe, 
process and special device management. 
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7.1 ABORT 


C Interface: 
LONG pid; 


ret = s_abort(pid); 
emask = e_termevent(swi,pid); 


ret = __ osif(F_ABORT,&parmbik); 


parmblk: 


4 
8 
Parameters: 
Swi Address of a software interrupt routine 
pid Process ID of target process to abort or to wait to 


terminate. Use 0 to specify calling process. 
Return Code: 


ret Error Code 
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Description: 


The synchronous ABORT SVC removes a process 
from the system. Any outstanding events for that 
process are canceled, opened files are closed, and 
memory is released. Performing an ABORT on the 
calling process is equivalent to an EXIT with a 
return code of E_ ABORTED. 


A process can only be aborted by another process 
with the same user and group or by a superuser. 


The asynchronous version of ABORT does not 
terminate the target process. Instead, it makes the 
target's termination an event. Specify a process ID 
(pid) of zero to have the program trap a control-C 
entered by the user or any other external abort. Use 
the software pee (swi) to control program flow 
from there. 


The return code from ABORT reflects only the 
Operating system’s attempt to notify a process to 
terminate. If the process has a termination swi that 
does not perform an exit, ABORT’s return code 
indicates success, but the process will still be 
running. | 
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7.2 ALTER 

C Interface: 
UWORD flags; 
LONG fnum: 
FRAME *dframe; 
RECT *drect; . 
BYTE alterb[6]; 


ret = s_alter(flags,fnum,dframe,drect,alterb); 
ret = __ osif(F_ALTER,&parmblk); 


parmbik: 
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Parameters: 


flags 


fnum 
dframe 


drect 


andO 
xor0 
and] 
xor] 
and2 
xor2 


Return Code: 


Bit map of 
bit 0: 1 
0 = 
bit 1: 1 
0 = 
bit 2: 1= 
0 = 


planes to alter. 


= Alter character plane 


7.2 ALTER 


Do not alter character plane 


= Alter attribute plane 


Do not alter attribute plane 


Alter extension plane 


Do not alter extension plane 


bits 3-15 are reserved. 


Console screen or border file number; use O to 
specify a memory FRAME | 


Address of FRAME to affect; 
indicate screen or border specified by fnum. 


use NULLPTR 


to 


Address of RECT specification indicating portion of 
FRAME to alter 


-alterb[O] = 


alterb[1] = 
alterb[2] = 
alterb[3] = 
alterb[4] = 
alterb[5] = 


ret 
Frror Code 


character plane AND 
character plane XOR 
attribute plane AND 
attribute plane XOR 
extension plane AND 
extension plane XOR 


7.2 ALTER 


Description: 
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ALTER changes a rectangular area of the specified 
FRAME. The Console Resource Manager changes 
each cell in the planes selected according to the 
AND and XOR values you specify for that plane. The 
rectangular area is defined by a RECT structure. You 
select the planes in the flag word. 


The FRAME can be a screen or memory FRAME. To 
specify a screen FRAME put its file number in the 
fnum field and a null pointer in the dframe field. To 
specify a memory FRAME, put a O in the fnum field 
and the FRAME’s address in the dframe field. 


The following table lists the AND and XOR bit values 
used to modify the destination byte or combine it 
with another value. 


Action Performed on Bit — Bit in Bit in 


in Destination Byte AND Byte XOR Byte 
Clear: 0 0 
Set 0 1 
As is 1 0 
Complement 1 1 


Logical Operation with Data 


and Bit in Destination Byte 


Load Data 0 data 
AND Data data 0 

XOR Data 1 data 
OR Data NOT data data 
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7.3 BWAIT 

C interface: 
UWORD clicks; 
LONG mask; 
LONG state; 


ret = s_bwait(clicks,fnum,mask,state); 
emask = e_bwait(swi,clicks,fnum,mask,state); 


ret = __ osif(F_BWAIT,&parmbik); 


parmbik: 


clicks 


7.3 BWAIT 


7.3 BWAIT 


Parameters: 


clicks 


fnum 


mask 


State 


Return Code: 


ret 


Description: 


7-8 


FiexOS Programmer's Guide 


Number of times the mouse enters this state within 
the “click‘interval” set up in the MOUSE Table after 
this call is made. If clicks is 0 and the mouse is 
already in this state, the event is already complete. 


Mouse file number 


Bit mask of buttons to consider. The lowest order 
bit is set if the first mouse button to the left is to 
be considered. The second lowest bit corresponds 
to the second button from the left. A total of 16 
mouse buttons can be supported in the low word of 
mask. 


Bit mask of buttons that define the button state 
given the mask that determines the buttons to 
ignore all together in the low word of state. 


Number of Clicks 


Error Code 


The BWAIT SVC allows the calling process to wait 
until a mouse button state is reached. The mask 
determines the number of mouse buttons the calling 
process wants considered. For example, by setting 
the mask appropriately, a one button mouse can be 
expected when there is more than one button. 


The clicks field allows the calling process to receive 
multi-click mouse input. When a user presses a 
mouse button, releases it and presses it again 
within the “click interval", the mouse has been 
double clicked. 
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If clicks is set to two, and a second click is not 
performed within the “click interval”, the event is 
considered complete. The return value indicates the 
number of clicks actually performed. If clicks ts set 
to zero, BWAIT returns a zero if the button state is 
already in the specified state. Otherwise, it returns 
one upon the first entry to the state. 


The “click interval” is changed in the MOUSE table 
through the SET SVC. 
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7.4 CANCEL 


C Interface: 


LONG 
LONG 


dmask 


dmask 


Parameters: 


. events 


Return Code: 


dmask 


Description: | 
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dmask:; 
events: 


s_cancel(events); 


__osif(F_CANCEL,events); 


Logical OR of event masks to be canceled 


Bit map of events that could not be canceled 
because they have already completed 


The CANCEL SVC terminates one or more specified 
asynchronous SVCs. The events argument is the 
logical OR of the event masks you want to cancel. 
The dmask return code indicates events. that, 
although requested for termination, had already 
completed. Use the RETURN SVC to get the return 
codes for these events so the event bits can be 
reused. | 
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7.5 CLOSE 

Interface: 
UWORD flags; 
BYTE option; 
LONG fnum; 
ret = s_close(flags,fnum); 


ret = __osif(F_CLOSE,&parmblk); 


parmblk: 


Parameters: 
option May be used by SPECIAL devices. 
flags bit 0: 1 = partial close (flush only) 
Q = full close 


bits 1-15 are reserved. 


fnum File number of file to be closed 


7.5 CLOSE 


Return Code: 


Description: 
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ret 
Error Code 


CLOSE disassociates an 1!/O stream from a file 
number. Before the close is performed, all 
outstanding asynchronous I/O is completed and 
locked file areas are unlocked. If a device error 
occurs on a full close, the file is closed making the 
file number invalid. | 


For all types of files, a partial close flushes the 
associated !/O buffer but leaves the file open. For 
disk files, a partial close updates the directory. 


For disk and pipe files and directories created with 
the temporary flag set, the last close deletes the 
files. This also applies to a file marked temporary 
because an attempt has been made to delete it 
while any process had it open. In this second case 
only, the closing process gets an error return code 
rather than success to indicate that the close also 
resulted in a file delete. 


WARNING: CLOSE with the “full close” option 
always disconnects an open file from the calling 
process regardless of error. This can cause a 
failure to flush intermediate buffers to media if the 
error is a physical error. 


Specifically, if a floppy drive door is open at the 
time of a close, the final flush does not occur. An 
application can avoid this problem by performing a 
“partial close” to flush all intermediate buffers. If an 
error is returned indicating an “open door”, the 
application can warn the user to replace the media 
and close the door before attempting the close 
operation again. 


FlexOS Programmer's Guide 7.5 CLOSE 


However, if any other activity occurs on the device 
from the time the door was originally opened, the 
“partial close” approach fails since all intermediate 
buffers have been discarded. In such a case, the 
application must assume the file has not been 
updated since the last successful partial close. 
After performing a successful partial close, the 
application can perform a full close to disassociate 
the file from the process. 


COMMAND FlexOS Programmer's Guide 


7.6 COMMAND 


C interface: 


UWORD _ flags; 

LONG pid, bufsiz; 

BYTE *command,*buffer; 
~ PINFO *procinfo; 


ret = s_command(flags,command,buffer,bufsiz,procinfo); 
emask = e_command(swi,&pid,flags,command,buffer,bufsiz,procinfo); 


ret = __ osif(F_COMMAND, &parmbik); 
parmblk: 


ee 
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Parameters: 


flags 


SWi 


command 


buffer 


bits 0-3 are reserved 


bit 4: 1 = No new process (set bit 5 to 1) 
O = New process (ignore bit 5) 


bit 5: 1 = Chain 
0 = Not implemented (returns E_IMPLEMENT error) 


bit 6: 1 = Do not release memory on termination 
of procedure if procedure uses the 
EXIT SVC with the stay resident flag set. 
0 = Not implemented (returns E_IMPLEMENT error) 


bit 7: 1 = Assign a new process family ID (FID) 
O = Keep the current process family ID (FID) 


bits 8-12 are reserved (must be Q). 


bit 13: 1 = Force case to media default 
0 = Do not affect name case 


bit 14: 1 = Literal command 
0 = Prefix substitution allowed 


bit 15: reserved (must be O) 


Address of a software interrupt routine 


- Address of 128-byte,  null-terminated — string 
indicating the name of the loadable file. 


Address of a variable length buffer containing a 
128-byte, null-terminated command tail and special 
information to be passed to the new process. (At 
most, the command tail can be 127 characters and 
one NULL byte long.) COMMAND puts the tail in the 
CMDENV table. Data after the first 128 bytes is put 
in the process’s heap. 
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The PROCESS table contains the heap address and 
size. Use this buffer area to pass an environment 
string, common data, or special information to the 


program. 
bufsize Size of buffer in bytes 
procinfo Address of the PINFO table. PINFO must be 
constructed as follows: 


ADDMEM 


20 = Length in bytes 


12 


16 


name: Process name 


prior: Process priority (user processes are usually 
set to 200) © 


maxmem: Maximum memory this process can own 
(larger minimum requirements specified by the 
command file supercede this amount) 


addmem: The amount of memory to be added to 
the minimum amount specified by the command file 
(FlexOS allocates the greater of the two values: 
maxmem or the sum of the command file’s specified 
minimum plus addmem) 


pid Address of new process ID. COMMAND puts the 
new process's 32-bit PID at this location when flag 
bit 4 equals QO and COMMAND  is_ called 
asynchronously. 
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Return Code: 


ret 


Description: 


Process completion status: 
High order word = 0 
Low order Word = return status (negative if error) 


Error Code: Indicates program load failure 


The COMMAND SVC creates a new process or 
chains a new program to the calling process. The 
value of flag bit 4 determines which action is taken. 
When flag bit 4 is set, use flag bit 7 to specify 
whether you want the current process family ID kept 
Or a new One assigned. 


The return code is a long value with two 
components: if the high order word is zero, the low 
Order word contains an utility return code. See 
Appendix B for a list of utility return codes. If the 
high order word is a negative number, the low order 
word cantains an onerating system error code A 
return code can be used in batch files as an 
argument in the IF ERRORLEVEL statement. 


When COMMAND is called synchronously, the return 
code is provided when the EXIT SVC is called by the 
program. When COMMAND is called asynchronously 
and a new process is requested, an event mask 
(emask) is returned and the new process ID is 
stored at the location indicated by pid. 


The chain option causes the calling process’s 
Current program to be overlaid with the new 
program. The process ID does not change. 


COMMAND 
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The COMMAND SVC opens the specified command 
file in EXECUTE mode without accepting reduced 
access. Any error in the attempt to open the file 
returns the file not found error. 


Priority of 200 is the recommended number for user 
processes. ‘Higher numbers have lower priority; 
lower numbers have higher priority. 
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7.7 CONTROL 


C interface: 


UWORD option; 
LONG pid,target,bufsiz,tpid; 
BYTE. *buffer; 


ret = s_control(option,pid,buffer,bufsiz,target,&tpid); 
emask = e_control(swi,option, pid, buffer,bufsiz,target,&tpid); 


ret = __ osif(F_CONTROL,&parmbik); 


parmblk: 


O=sync 


e 


bufsiz 


CONTROL 


Parameters: 


option 


Swi 


pid 
‘buffer 


bufsiz 


target 


&tpid 
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0 - Invalid 

1 - Load Program for control 
2 - Delete Program 

3 - Read Target Code Memory 
4 - Read Target Data Memory 
5 - Write Target Code Memory 
6 - Write Target Data Memory 
7 - Read Target Registers 

8 - Write Target Registers 

9 - Go 

10 - Single Step (Trace) 

11 - Reserved (Force Halt) 

12 - 13 Reserved (All Exception Traps ON,OFF) 
14 - Select Exception Trap ON 
15 - Select Exception Trap OFF 
16 - 255 are reserved 


Address of a software interrupt routine 


For option 1, a pointer to command _ file 
specification; for options 2-15, the process ID of the 
target process 


Address of buffer in calling process’s address space; 
the purpose of this buffer depends on the option 
selected. | 


Size of buffer in bytes 


Address in controlled process’s address space: the 
purpose of this buffer depends upon the option 
selected. 


Target process address: tpid is used only with 
option 1; see the first section of the chip 
supplement to this book for the description of its 
use. | 
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Return Code: 


ret 


Description: 


Error Code 


The CONTROL SVC controls the execution of one or 
more child processes. Use the CONTROL options to 
select debugging functions such’ as __— setting 
breakpoints, modifying memory or registers, and 
starting and stopping process execution. The use of 
the pid, buffer, target, and &tpid arguments depends 
upon the option selected. 


Option 1--Load: Use this option to create the 
target process. The pid, buffer, bufsiz, target, and 
&tpid arguments have the same purpose as the 
command, buffer, bufsiz, procinfo, and  &tpid 
arguments in the COMMAND SVC. CONTROL opens 
the specified program (command file) in Execute, 
Read mode with no reduced access. When called 
synchronously, the load option returns when the 
program is loaded; the return code indicates the 
success or failure of the operation. Similarly, the 
asynchronous CONTROL load event is complete 
when the program is loaded. Use the RETURN SVC 
to get the return code. 


Option 2--Delete: Use this option to terminate the 
program. pid specifies the target process to 
terminate. 


Options 3 and 4--Read target code or data 
memory: Use these options to transfer a portion of 
the target process’s memory to the calling process's 
memory. pid specifies the target process, the buffer 
address points to the calling process’s destination 
buffer area, and target contains the logical address 
in the target process from which to begin the 
transfer. The bufsiz value indicates the number of 
bytes to be transferred. 
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Options 5 and 6--Write target code or data 
memory: Use these options to transfer a portion of 
the calling process’s memory to the target process’s 
memory. pid specifies the target process, buffer 
contains the pointer to the calling process’s source 
buffer, and target contains the first logical ‘address 
of the target’s destination buffer. The  bufsiz 
indicates the number of bytes to be transferred. 


Options 7 and 8--Read and write target registers: 
Use these options to transfer the target process's 
register data to or from the calling process’s buffer. 
pid specifies the target process and buffer contains 
the pointer to the destination or source buffer. 


Option 9--Go: Use this option to commence 
execution of the target program. Execution 
proceeds until one of the following conditions is 
encountered. The number shown in parenthesis 
indicates the condition’s return code. 


@ Error code on CONTROL request (<0) 

® Target process EXIT (0) 

® Target process exception (>0): This condition 
exists when break point set by CONTROL option 
14 or by the EXCEPTION SVC is encountered. 

@® Target about to be aborted through an external 
ABORT or Control-C (512): 512 is the return 
code for the COMMAND SVC when using the go 
option. 


Option 10--Trace: Use this option to step through 
the target program one instruction at a time. pid 
specifies the target process and bufsiz must be 1. 
The return code is the same as the Go option. 
Resume execution with Go or another Trace. 
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Options 14 and 15--Trap ON and OFF: Use option 
14 to set target program break points at exception 
handling routines and SVCs; use option 15 to have 
break points ignored. pid specifies the target 
process and the target value contains a_ buffer 
pointer indicating the exception numbers to break. 
on (see EXCEPTION). When an exception set by the 
target program is reached, target program execution 
proceeds with the interrupt service routine (isr). 
When an exception set by CONTROL is reached, 
target program execution stops and control returns 
to the calling process. 


You set break points by writing a “break point” 
instruction into the target buffer, turning the break 
point exception trap on, and using the Go option. A 
return code greater than O, where the number 
indicates the exception number, indicates that a 
break point has been encountered. To proceed, 
restore the target process code and _ “set _ the 


e + ti e + e @ 
instruction pointer to the break point location. 
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7.8 COPY 


C interface: . 


UWORD flags; 

LONG fnum; 

FRAME *sframe,*dframe; 
RECT *srect,*drect; 


ret = s_copy(flags,fnum,dframe,drect,sframe,srect); 
ret = __ osif(F_COPY,&parmblk); 


parmbIlk: 


sframe 
| srect 


Parameters: 


flags Bit map of planes to copy 


bit 0: 1 = Copy character plane 
0 = Do not copy character plane 
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fnum 


dframe 


- drect 


sframe 


srect 


Return Code: 


ret, 


Description: 


bit 1: 1 = Copy attribute plane 
0 = Do not copy attribute plane 


bit 2: 1 = Copy extension plane 
0 = Do not copy extension plane 


bits 3-15 are reserved. 


Console screen or border file number 


Address of destination FRAME; NULLPTR indicates 
screen or border specified by fnum. 


Address of destination RECT description 


Address of source FRAME: NULLPTR indicates screen 
or border specified by fnum. 


Address of source RECT description 


Error Code 


The COPY SVC copies the specified plane contents 
from one rectangle to another on the same or 
different FRAMEs. The drect and srect rectangles are 
defined in the form of RECT structures. If either the 
dframe or sframe FRAME specifications are O, the 
file number in fnum indicates the proper FRAME. The 
RECT and FRAME data structures are described in 
Section 3. 


The source and destination rectangles do not need 
to be the same size and can overlap on the same 
screen. When the rectangles are different sizes, 
COPY trims off the larger. The upper lefthand 
corner of both rectangles is used as the point of 
reference. 
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7.9 CREATE 


7.9.1 Create a File, Directory, or Pipe 


C Interface: 


UWORD flags,record_size,security; 
BYTE option,*name; 


LONG size; 
fnum = s_create(option,flags,name,record_size,security,size); 
ret = __ osif(F_CREATE,&parmblk); 


parmblk: 


Parameters: 


Disk file or pipe 

Disk directory 

= Virtual console (described separately) 
-~255 Reserved 


option 
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flags 


bit 0: 1 


0 


Create a File, Directory, or Pipe 


Delete file/set attributes access 
No delete/set access 


bit 1: Reserved (must be 0) 


bit 2: 1 
0 
bit 3: 1 
0 
bit 4: 1 
bit 5: 1 
0 
bit 6: 1 
bit 7: 1 
0 
bit 8: 1 
‘0 
bit 9: 1 
0 
bit 10: 1 
0 
bit 11 is 
bit 12: 1 
0 
bit 13: 1 
0 


= Write 


No Write 


= Read 


No Read 


= Shared 


Exclusive 


Allow Shared Reads if Shared 
Allow Shared R/W if Shared 


= Shared File Pointer 


Unique File Pointer 


= Zero Fill contiguous region* 


Do Not Zero Fill 


Temporary — Delete on Last Close 
Permanent 


Allocate space in a contiguous block* 
Contiguous block allocation not required 


= Delete File if it already exists 


Return Error if file exists 


reserved (must be zero) 


= Use specified security 
Use default security (see ENVIRON table) 


Force Case to Media Default 
Do not Force Case on name 
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name 


record_size 


security 


15 14 13 
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bit 14: 1 = Literal Name 
O = Prefix Substitution Allowed 


bit 15 is reserved 


* Only valid if file’s size value is non-zero. © 


Address of NULL-terminated name string: if file is 
not in default:, the string must include -path 
specification or a previously defined logical name 
(maximum 128 bytes, NULL terminated) 


File record size: The READ, WRITE and LOCK SVCs 
use this value to make sure the requested action 
falls on record boundaries. Use a record_size of 0 
OR 1 if you want no boundary checks performed (a 
record_size of 0 is equivalent to a record_size of 1). 
FlexOS considers disk files and pipes with a record 
size of 1 as 8-bit files. Files with a record size of 2 
are considered 16-bit files. | 


File Security Word (FSW) describing access rights 


for file owner, group and world. The FSW is 


formatted as follows: 
11109 8 7 6 5 4 3 2 1 +0 


| ~«— Reserved—» | «— WORLD —» | «— GROUP —» | <— OWNER —» 
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User access is restriced according to the privilege 
level set for owner, group, and world users. See 
Section 1.4.2 for a description of the R(ead), W(rite), 
E(xecute), and D(elete) privileges. This value is only 
valid when flag bit 12 is on. Otherwise, the default 
security specified in the ENVIRON table is used. 
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size 


Return Code: 


fnum 


ret 


Description: 


Number of bytes to reserve for the file: For disk 
files, the space is contiguous only if bit 9 is set. Use 
a size value of 0 when you create directories and 
files whose size is dynamic. For pipes, the size 
value specifies the size of the pipe buffer. Size is 
not applicable to virtual consoles. 


The file number: The file is automatically opened. 
The calling process must close the file if no access 
is needed. If the security field conflicts with the 
flag bits 0-6, then the file is created but not 
opened, and an error code is returned. 


Error Code 


CREATE option 0 adds a new disk file to a directory 
Or a new pipe to the pipe system. CREATE option 1 
makes a new directory. The record_size and size 
fields are only applicable to option 0; for directories, 
set these values to zero. 
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7.9.2 Create a Virtual Console 


C interface: 


* UWORD flags; 
LONG screen_fnum; 
WORD rows,columns; 
BYTE option,top,bottom, left, right; 


fnum = s_vccreate(flags,screen_fnum,rows,columns,top,bottom_left, 
right); 


ret = __osif(F_CREATE,&parmblk); 


parmblk: 


ee ee 
hoe Sa ea 


Parameters: 
option 0 = Disk file or pipe (invalid here) 
1 = Disk directory (invalid here) 
2 = Virtual console (only valid choice) 
3-255 Reserved 
flags bit 0: 1 = Bit mapped screen 


Q = Character mapped screen 
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screen_fnum 


rows 


columns 


top 
bottom 
left 
right 


bit 1: 1 = Bit mapped borders 
0 = Character mapped borders 


bit 2: 


= 
if 


Sized as specified 
0 = Same size as parent 


bit 3: 1 = Remove parent screen memory and 
restore on delete of last child’s 
virtual console. 
Q = Keep screen memory and allow writing 
to the parent screen 


bits 4 - 7 are reserved 


bit 8: 1 = Temporary - delete on last close 
0 = Permanent | 


bits 9 - 15 are reserved 


File number of the parent console file on which new 


virtual console is based. 


Number of character rows in new virtual console. If 
flag bit 2 is zero, the number of rows is the same 
as the parent. 


Number of character columns in the new virtual 
console. If flag bit 2 is zero, the number of 
columns is the same as the parent. 


Height of top border in characters 
Height of bottom border in characters 
Width of left border in characters 


Width of right border in characters 
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Return Code: 


fnum 


ret 


Description: 


1>32 


New virtual console’s file number: Use this number 
to GET and SET the virtual console’s VCONSOLE 
table. Only the process that created a virtual 
console can change VCONSOLE values. The number 
returned is not the VCNUM referenced in the 
VCONSOLE and CONSOLE tables. 


Error Code 


This CREATE SVC option makes a new virtual 
console. Before you can CREATE a child virtual 
console, you must have at least write access to the 
parent console specified in screen_fnum. The row 
and column values do not need to be the same as 
the parent console’s. 


CREATE opens the new virtual console, which allows 
you to change values in the VCONSOLE table. No 
other process has access rights to this. table. 
CREATE does not open the console file. Before you 
can read from and write to a new virtual console, 
you must open the console file. The name of this 
file is vcxxx/console where xxx is a 3-digit number 
indicating the virtual console’s number. 


Unlike the s_create call, the s_vccreate call does not 
accept an option. 
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7.10 DEFINE 


C interface: 


UWORD flags; 
BYTE *Iname, *prefix; 
LONG size; 


ret = s_define(flags,Iname,prefix,size); 
ret = __osif(F_DEFINE,&parmbik); 


parmblk: 


Parameters: 


flags bit 0: 1 = Reference SYSDEF table 
0 = Reference PROCDEF table 


bit 1: 1 = Return prefix string 
Q = Set prefix string 


bits 2-13 are reserved 


bit 14: 1 = Literal returned prefix 
0 = Translated prefix 


DEFINE 


iname 


prefix 


size 


Return Code: 


ret 


Description: 
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If bit 14 = 1, the exact prefix string is returned. 
Otherwise, FlexOS translates the logical name until 
it cannot find another entry. This is done for a 
maximum of 99 times, after which an error is 
returned. 


Address of logical name: Iname is a NULL 
terminated string no longer than ten characters. 


Address of prefix string buffer: If flag bit 1 = 0, 
prefix contents replace Iname. Use NULLPTR to 
delete a Iname. Prefix string must be NULL- 
terminated and cannot exceed 128 bytes. If flag bit 
1 = 1, DEFINE stores the current prefix at this 
address. 


Size of prefix buffer; cannot exceed 128 bytes 


Error Code 


The DEFINE SVC either gives a logical name to a 
prefix string or returns the prefix for the specified 
name. Use DEFINE to redirect 1/O from hardcoded 
filenames to other filenames or to make program- 
related assignments for stdin, stdout, stderr, and 
other logical names. The logical name _ cannot 
contain wildcard characters or path delimiters. 


Logical name prefixes are kept in two tables: The 
SYSDEF table holds the system-wide logical name 
definitions and the PROCDEF table’ holds the 
process-bound logical name_ definitions. Child 
processes inherit their parent’s PROCDEF table. 
However, DEFINE changes’ affect the calling 
process’s PROCDEF table only. See Section 8 for the 
description of the SYSDEF and PROCDEF tables. 
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Only privileged processes (user and group numbers 
equal 0) can call DEFINE to modify SYSDEF table 
assignments. No special privilege is required to 
return a prefix from the SYSDEF table. 


SVCs using names to indicate files have options to 
ignore prefix translation. When prefix translation is 
requested, the process’s PROCDEF table is checked 
before the SYSDEF table. 


When the file name specified does not include a 
device, FlexOS applies the special device name 
“default:” to the file name before attempting prefix 
substitution. Setting the current default directory of 
a process is therefore done by defining “default:”. 
Since indirection is allowed, the user can_ set 
“default:” to another defined name such as “system:” 
or “home:”. This implies the default directory is not 
necessarily legal. Programs that set the default 
directory should check’ for legality through 
accessing “default:” in some manner. | 


FlexOS does not check for loops in the DEFINE SVC. 
It does prevent infinite loops by only allowing 99 
iterations when converting a name. FlexOS also 
insures that the logical name and the prefix name 
are not the same. 


FlexOS does not check for actual device and 
directory names. Therefore, you can use DEFINE to 
store any string substitution information needed at 
either the system or process level. For example, 
you can store command macros for later translation 
either by the COMMAND SVC or a user interface 
program. 


The “system:” and “boot:” logical names are initially 
defined at boot time by the BOOTINIT process. 
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7.11 DELETE 


C interface: 


UWORD flags; 
BYTE *name; 
ret = s_delete(flags,name); 


ret = _ osif(F_DELETE,&parmblk); 


parmbik: 


Parameters: 
flags bits O - 12 are reserved 
bit 13: 1 = Force case to media default 
0 = Do not affect name case 
bit 14: 1 = Literal name 
0 = Prefix substitution allowed 
bit 15 is reserved 
name Address of name of file to be deleted 
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Return Code: 


ret 


Description: 


Error Code 


The DELETE SVC removes an existing disk file, pipe, 
virtual console, or directory file. Before you can 
delete a virtual console, it must have no open files 
or child consoles. Before you can delete a directory 
file, it must be empty. 


An attempt to delete an open file returns success, 
however, the file is not immediately deleted. Instead, 
FlexOS marks the file as temporary. The temporary 
classification results in a file that remains available 
until the last close, when it is deleted. 
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7.12 DEVLOCK 


C Interface: 


BYTE option; 
LONG fnum; 


ret = s_devlock(option,fnum); 


ret = _ osif(F_DEVLOCK,&parmbik); 
parmblk: 
of eo le [om 
2 
ptm 
Parameters: 
option 0 - Lock for process 
1 - Lock for process family 
2 - Unlock 
fnum File number of the opened device 
Return Code: 
ret Error Code 
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Description: 


The DEVLOCK SVC locks or unlocks a_ device; 
restricting or releasing access rights to the device. 
Use the option field to indicate whether you want 
access restricted to the calling process alone or to 
the calling process and other proeyases with the 
same family ID (FID). 


FlexOS does not lock the device and returns an 
error if another process has an open file on the 
device. (FlexOS allows the calling process to have 
open files, however.) It also returns an error if the 
device was protected against DEVLOCK when it was 
installed. 


The device can only be unlocked by the process 
that initiated the lock. The lock is automatically 
removed when the process terminates and when the 
device file is fully closed. If the lock is applied to 
allow only related processes access to the device, 
FlexOS removes the restriction when the initiating 
process terminates; related processes no longer 
have exclusive access. 
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7.13 DISABLE 


c Interface: 

s_disable(); 

ret = __osif(F_DISABLE,O); 
Parameters: 

NONE 
Return Code: 


NONE 


Description: The DISABLE SVC suspends the calling process's 
program jumps to software interrupt routines (SWls). 
DISABLE does not, however, suspend software 
interrupts generated through the EXCEPTION SVC. 
FiexOS triggers SWlis for events completed while 
software interrupts are DISABLEd when the ENABLE . 
SVC is called. 
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7.14 ENABLE 


C Interface: 

s_enable(); 

ret = __osif(F_ENABLE,0); 
Parameters: 

NONE 
Return Code: 


NONE 


Description: The ENABLE SVC restores program jumps to 
software interrupt routines (SWls). (The DISABLE SVC 
suspends their execution.) After ENABLE is called, 
FlexOS triggers the SWls for events completed while 
software interrupts were DISABLEd. 
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7.15 EXCEPTION 


C interface: 


WORD number; 
LONG . isr; 


ret = s_exception(number,isr); 


ret = __osif(F_EXCEPTION,&parmbik); 


parmbik: 


Parameters: 
number exception number 
isr Address of Interrupt Service Routine. A NULL pointer 


removes the software interrupt for the exception 
number specified. 


Return Code: 
ret Error Code 


Description: The EXCEPTION SVC allows a user program to trap 
various conditions that would otherwise result in a 
program abort or error. 
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EXCEPTION 


The number parameter is a 16-bit integer specifying 
the exception condition to trap. Exception condition 
numbers are assigned as shown in Table 7-1; see 
the first section of the chip supplement to this book 
for the relationship between your microprocessor’s 
and FlexOS‘s condition numbers. 


Table 7-1. Exception Condition Numbers 


Number 


TOM RON AOMPANAMTAWN=O0 


18 
19-255 
256+n 

512-64K 


Condition 


Non-existent memory 
Memory boundary error 
legal instruction 
Divide by zero 

Bound exception 
Overflow error 
Privilege violation 


Trace 


Breakpoint 
Floating point exception 
Stack fault 


Emulated 
Emulated 
Emulated 
Emulated 
Emulated 
Emulated 
Emulated 
Emulated 
Reserved 
Software 
Reserved 


instruction group O 
instruction group 1 
instruction group 2 
instruction group 3 
instruction group 4 
instruction group 5 
instruction group 6 
instruction group 7 


interrupt n 


EXCEPTION 
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Emulated instruction group O is reserved for 
software emulation of floating point hardware. Refer 
to programmer guide supplements for other 
emulation group assignments. 


The Interrupt Service Routine is a machine-specific 
routine that must save and restore machine state if 
it is to return to the program causing the exception. 
This includes an “Interrupt Return” tailored to the 
CPU architecture to exit the routine. Be careful to 
monitor your stack utilization; your isr may have to 
do a stack switch for a program that ts tight on 
stack space. This happens especially when the 
exception occurs in procedure code loaded through 
the COMMAND SVC. 
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7.16 EXIT 


C Interface: 
LONG 


S_exit(status); 


status; /*System error code or utility return code*/ 


ret = _ osif(F_EXIT,status),; 


Parameters: 


Status 


Return Code: 


A 32-bit value setting exit flags in the high order 
word and passing completion status in the low 
order word. 


Set exit flag bit O (status bit 16) to 1 to keep 
memory resident. Otherwise, FlexOS releases the 
terminating processes memory. Exit flag bits 71 - 15 
are reserved and must be OQ. The keep memory 
resident flag is only valid when the process is 
created with COMMAND flag bits 5 and 6 set. See 


Section 7.6 


The completion status word is returned to 
terminating process’s parent process. 


NONE to calling process 
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Description: 
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The EXIT SVC terminates the calling process, returns 
control to FlexOS, and passes back the completion 
status value to the parent process. Any outstanding 
events are cancelled and open _ files closed. 
Depending on status bit 32 (exit flag bit 16), the 
terminating process's memory allocation is either 
released or kept resident. 


After a process calls EXIT, its parent's COMMAND 
call completes. The completion status code is 
placed into the low order WORD of the return code 
with the high order word set to 0. (If exit flag 6 was 
set, FlexOS resets it.) See Appendix B for utility 
return codes. 


FlexOS sets the high bit of the completion status 
word to form a negative number when the attempt 
to create the process resulted in an error or the 
process was abnormally terminated. You can use 
the remainder of the bits to return a value to the 
parent process. By convention, a 0 value is used to 
indicate success while positive values indicate some 
form of partial completion. 
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7.17 GET 


C Interface: 


UWORD flags; 

BYTE table,*buffer; 
LONG id, bufsiz; 

ret = s_get(table,id,buffer,bufsiz); 
ret = __ osif(F_GET,&parmbik); 
parmblk: 


GET 


Parameters: 


Return Code: 


Description: 
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Table Number 


bits 0-7 can be used for SPECIAL devices bits 8-15 
are reserved 


File number or process ID 


Address of buffer to place partial or complete table 
contents 


Size of buffer in bytes 


Error Code 


The GET SVC stores partial or full table contents in 
the buffer specified. You specify the table by its 
number and, when there is more than one table with 
the same number, by a unique identifier. If the 
bufsiz is less than the size of the table structure, 
only the table contents up to that byte are stored. 


Depending on the table type, the table ID is either a 
process ID or a file number. The table descriptions 
in Section 8 indicate what the ID is for each table. 
Not all tables require an ID. USe a NULL ID value for 
these GET calls. | 
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7.18 GIVE 


C interface: 


LONG 


ret 


ret 


parmblk: 


Parameters: 


fnum 


Return Code: 


ret 


fnum; 
s_give(fnum); 


__osif(F_GIVE,&parmblk); 


File number of virtual console whose virtual 
keyboard you want mapped to _ the _ physical 
keyboard. 


Error Code 
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Description: 
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The GIVE SVC transfers access to the physical 
keyboard and mouse from the current’ virtual 
console to the virtual console specified by fnum. 
The virtual console getting ownership must be the 
virtual console for the process making the call or a 
child of that virtual console. Keyboard and mouse 
ownership is returned through the KCTRL SVC. 


Keyboard and mouse ownership is always passed 
from one virtual console to another as a unit; they 
cannot be separated. 


All characters in the previous owner's keyboard 
buffer are transferred into the new owner's keyboard 
buffer. Characters read subsequently from the 
physical keyboard are appended to the end of the 
characters in the buffer. 
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7.19 GSX - Perform Graphic SVC 


C Interface: 


ret = s_gsx(); 

ret = __ osif(F_GSX,&parmblk); 

parmbIlk: 
of 0 | option | 
, a 
Fs 

Parameters: 
PB Address of GSX Parameter Block 
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GSX Parameter Block format: 


ep intin 
2 
2 
wets 
: 
option 0 normal GSX call 
1 VDI aborting due to a CTRL-C. 
Return Code: 
ret Error Code 
Description: The GSX SVC allows the calling process to pemer 


a Graphics operation on the indicated file. 
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7.20 INSTALL 

C Interface: 
BYTE option,*devname,*parm; 
UWORD flags; 


ret = s_install(option,flags,devname,parm); 
ret = __ osif(F_LINSTALL,&parmbik); 


parmbik: 


devname 


Parameters: 
option Q - Remove previously installed driver unit. 


devname = device driver name 
parm = NULL 


1 - Load device driver from disk 


devname = device driver name for unit 0 
parm Loadable driver disk file name 
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2 - Add unit to existing device driver 


devname = device driver name for new unit 
parm = device driver name for unit 0 


3 - Link a subdriver to a device driver 


devname = Front end device driver name 
parm = Subdriver device driver name 


These flags are used for options 1 and 2 only. 


Raw SET allowed 
Raw SET not allowed 


bit 0: 1 
0 


bit 1: Reserved (must be 0) 


bit 2: 1 = Raw WRITE allowed 
0 = Raw WRITE not allowed 


bit 3: 1 = Raw READ allowed 
= Raw READ not allowed 


bit 4: 1 = Shared access allowed 
O = Exclusive access only 
bit 5: 1 = Removable device 
0 = Permanent device 
bit 6: 1 = DEVLOCKs allowed 
0 = DEVLOCKs not allowed 
bit 7: 1 = Shared access only 


O = Exclusive access allowed 


bit 8: 1 = Allow device partitions 


0 = Do not allow partitions 


bit 9: = Verify after disk writes 


Do not verify after disk writes 


oS —_ 
I 
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devname 


parm 


Return Code: 


ret 


Description: 


bits 10 - 12 are reserved and must be O 


bit 13: 1 = Force case to media default 
0 = Do not force case 


bit 14: 1 = Literal load name 
O = Prefix substitution on load name 


bit 15 is reserved and must be 0 


Address of the device name 


Depending on the option a null pointer or the 
address of the loadable disk driver file name, unit O 
device name, or subdevice name. 


Error Code 


The INSTALL SVC loads a device driver, removes a 
device driver, adds a unit to an existing device 
driver, or associates a subdevice to an existing 
device driver. The calling process must have group 
and user IDs of O to call INSTALL. INSTALL’s 
devname and parm values are different for each 
option. 


The device privileges set by the driver override 
those set by your INSTALL flags. This prevents you, 
for example, from opening a printer device with read 
access. 


If a physical device driver has more than one unit, 


you must’ specify a unique device name to 


distinguish each unit. Put the unit’s name in the 
devname field and specify the physical device driver 
in the parm field. devname and parm values must be 
null terminated and are limited to 128 bytes. 


INSTALL 
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When you call option 3, both drivers must be 
already installed. 


Flag bit 8 is used only by the disk resource manager 
and indicates whether or not the fixed disk device 
can have partitions. A disk with partitions cannot 
be formatted when installed with this bit on. Flag 
bit 9 is also used only by the disk resource 
manager. Set it when you want to verify every write 
to disk. Checksum verification is done. 
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7.21 KCTRL 


C interface: 


LONG 
UWORD 
UWORD 
UWORD 
RECT 


ret 
ret 
ret 


parmblk: 


fnum; 

nranges; 

flags,beg 1,beg2,beg3,beg4; 
end1,end2,end3,end4; 
region; 


s_kctrl(fnum,nranges,beg1,end1,beg2,end2,...end4); 
s_mctrl(fnum,region); | 
__osif(F_KCTRL,&parmblk); 


(if mouse control) 


12 | 
| region 
16 
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KCTRL 


Parameters: 


flags 


nranges 
fnum 
begn 


endn 


region 


Return Code: 


ret 


Description: 
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Reserved, must be 0 
bit 0: 1 = Mouse control 
0 = Character control 


lf O, keyboard ownership is controlled through 
characters typed on the keyboard and the begin 
range and end range parameters are required. If 1, 
keyboard ownership is controlled through mouse 
movement and a region is required. 


The number of beginning and ending ranges to 
follow--maximum 4. | 


Console file number of console to get keyboard; 
must be console file of the parent virtual console. 


First character in range of characters; pressing any 
character in range causes keyboard to return to 
specified console. | 


Last character in the range. 


RECT structure defining a character rectangle on the 
parent’s virtual console. 


Error Code 


The KCTRL SVC transfers keyboard ownership to the 
console file specified by fnum when a character is 
entered that falls within any of the four ranges 
specified. The initial transfer of ownership is 
conferred with the GIVE SVC. 
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You can specify up to four character ranges. The 
ranges are inclusive of the first and last characters. 
A single character is specified by using it as the 
beginning and ending character. When a character 
falling in the range is typed, that character and all 
subsequent characters are diverted to the parent 
console file’s keyboard buffer. The process 
controlling the virtual consoles can either give 
control of the keyboard to another virtual console or 
take some special action on behalf of the user. 


You can also use mouse position to change 
keyboard and mouse ownership. In this case you 
specify a RECT (see Section 3 for the RECT 
description) on the parent console in which the 
mouse form must be resident. This region must be 
within the virtual console. When the mouse leaves 
the region, keyboard and mouse ownership go back 
to the parent. 
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7.22 LOCK 


C interface: 


UWORD flags; 
LONG fnum,offset,nbytes; 


ret = s_lock(flags,fnum,offset,nbytes); 
emask = e_lock(swi,flags,fnum,offset,nbytes); 
ret = __osif(F_LOCK,&parmblk); 


parmblk: 


Parameters: 


flags bits 0 and 1 select the LOCK mode 


Unlock 

Exclusive lock 
Exclusive write lock 
= Shared write lock 


0 
1 
2 
3 


bits 2-3 are reserved (must be 0) 
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bit 4: 1 = Return error on lock conflict 
0 = Wait on lock conflict 


bits 5-7 are reserved (must be 0) 


bits 8 and 9 determine how the offset field is 
interpreted 


O = Relative to beginning of file 
= Relative to file pointer 
Relative to end of file 


NO o_o 


bits 10-15 are reserved (must be OQ) 


swi Address of software interrupt routine 

fnum File number whose contents you want to lock and 
unlock 

offset Offset of region to lock in file 


Return Code: 
ret Error Code 


Description: The LOCK SVC either locks or unlocks a region of a 
disk file, restricting or releasing access rights in the 
process. The disk file is specified by fnum and the 
area to be locked is determined by flag bits 8 and 9, 
Offset, and nbytes. The Disk Resource Manager 
verifies that offset and nbytes define a region that 
falls on record boundaries for files created with a 
record size. If you specify a region that does not fall 
On a record boundary, no records are locked or 
unlocked and an error message is returned. 


The lock modes selected by flag bits 0 and 1 are 
defined as follows: 
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@ 1--Exclusive lock: Prevents other processes 
from flocking, reading from, writing. to, or 
deleting the region. | | 


@ 2--Exclusive write lock: Lets other processes 
read from the region but prevents them from 
locking, writing to, or deleting the region. 


@ 3--Shared write lock: Allows other processes 
to read from and establish a shared write lock 
on but prevents them from writing to the 
region ; 


Flag bit 4 determines what happens when the region 
requested is already locked in an exclusive mode. 
When you set bit 4 to 1, an error code is returned; 
when you set bit 4 to 0, LOCK waits for the region 
to be unlocked, locks the region, and returns. 


The offset of the lock region in the file is, 
depending on the value in flag bits 8 and 9Y, relative 
to the beginning of the file, the current file pointer, 
or the end of the file. The file pointer location is 
modified by the READ, WRITE and SEEK SVCs. The 
nbytes value determines how many bytes are 
locked. | | 


To unlock a region set flag bits 0 and 1 to 0. The 
offset indicates the first byte of the region to unlock 
and nbytes the number of bytes to unlock. Because 
the region unlocked is independent of the region 
initially locked, you can lock a large region of a file 
and then release portions as the lock becomes 
unnecessary so that other processes .can have 
access. Once a region is unlocked, it can be locked 
by another process. 


An unlock specification with flags and offset values 
equal to 0 and nbytes equal to OxFFFFFFFF removes 
all locks on the file made by the calling process. 
The number of unlock calls does not have to match 


the number of lock calls. 
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7.23; LOOKUP 


C interface: 


UWORD flags; 
BYTE table,*name,*buffer; 
LONG key,bufsiz,itemsiz,nfound; 


nfound = s_lookup(table, flags,name,buffer,bufsiz,itemsiz,key); 
ret = _ osif(F_LOOKUP,&parmblk); 


parmblk: 


| — 0 


Parameters: 


table Table Number (Table 10-1 lists the table numbers) 
flags bits 0 - 7 are dependent on table type 


bits 8 -12 are reserved (must be Q) 
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name 


Return Code: 
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nfound 
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bit 13: 1 = Force name case to media default 


0 = Do not change name case 
bit 14: 1 = Literal name 
0 = Prefix translation allowed 


bit 15 is reserved (must be 0) 


Address of the table name to search for; names are 
case sensitive. 


Address of buffer to store information collected. 


Size of buffer in bytes. 


The number of bytes to store from each table. If 
itemsiz is less than the table size, only that many 
bytes from each table found are written in the 
buffer. If itemsiz is greater than the table size, the 
excess area is not modified. 


Key from which to continue searching. The key 
value depends on the table type. Each table allowing 
LOOKUP specifies a key for continued search. The 
LOOKUP SVC continues the search from the first 
item after the key. A key value of O always starts 
the LOOKUP search from the beginning of the table. 


Number of tables found. LOOKUP stops searching 
when the end of the buffer is reached or there are 
no more tables. If the last table does not fit into the 
remaining buffer space, it is discarded. 


Error Code 
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Description: 


The LOOKUP SVC searches the system tables for 
those matching the table and name specified. The 
key field is used to specify the starting point for the 
search. A key value of zero specifies the beginning. 
A table’s key value is defined by the resource 
manager responsible for that table. When a match is 
found the table, or an excerpt corresponding to the 
itemsiz in length, is copied into the buffer. The 
search continues until the buffer is filled or there 
are no more tables. 


The name specification is limited to 128 bytes and 
must be null terminated. You can use wildcards in 
the name specification. However, you are restricted 
to the lowest level of a path name--that is, files 
within a directory and devices on a node. The name 
“*" is translated to mean “default:*”. 


Table names are case sensitive and you must enter 
your specification with the same case letters to get 
a match. This is also true when you use wildcards. 
For example, the entry “s*” returns only those tables 
beginning with a lowercase s. 


A return of O indicates success, but means that 
LOOKUP found no tables. 


Table numbers, names, keys and the use of flag bits 
Q through 7 are described in Section 8. 
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1.24 MALLOC 


C Interface: 


LONG *mpbptr,mpbsiz; 
BYTE option; 


ret = s_malloc(option,mpbptr); 


ret = __osif(F_MALLOC,&parmblk); _ 


parmblk: 


Parameters: 
option © 0 = Expand existing heap 
1 = Allocate a new heap 
mpbptr Address of Memory Parameter Block 
mpbsiz Size of Memory Parameter Block in bytes 
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The Memory Parameter Block must have the following format: 


ee 
ee 


8 


Return Code: 


ret 


Description: 


max 


start: For option equals 0, set the base address of 
the heap segment to be expanded in this field. 
MALLOC writes the base address of the added 
memory portion before it returns. For option equals 
1, set this field to zero. MALLOC fills in the base 
address of the new heap here. 


min: Specify the minimum number of bytes 
required. MALLOC fills in the actual number 
allocated before returning. 


max: Specify the maximum number of bytes 
required. MALLOC does not change your entry. 


Error Code 


MALLOC either adds contiguous memory to the end 
of an existing heap or allocates a new heap. Use the 
option field to select one or the other and the 
Memory Parameter Block to specify the minimum 
and maximum memory requirements. Set the 
Memory Parameter Block’s start parameter to the 


base address of the existing heap for option O or to 


zero for option 1. 
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Note: Process are not automatically given an initial. 
heap allocation. Consequently, option 1 must be 
called the first time heap space is needed. 


When you select option 0, MALLOC extends the 
designated heap contiguously and modifies your 
Memory Parameter Block’s start and min parameters 
to indicate the new allocation’s starting address and 
actual allocation, respectively. The original heap’s 
base address (which is present PROCESS table) and 
contents remain unchanged. 


When you select option 1, the new heap may or 
may not be contiguous with any _ previously 
allocated heap. MALLOC modifies your Memory 
Parameter Block's start and min values to indicate 
the new heap’s base address and actual allocation. 
These new values also appear as the PROCESS 
table’s HEAP and HSIZE parameters. The new heap 
may be allocated such that an existing heap is no 
longer expandable. 


MALLOC use is affected by the type of processor. 
See the supplement corresponding to your 
processor for more information. | 
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7.25 MFREE 


C Interface: 

BYTE ‘start; 

S_mfree(start); 

ret = __osif(F_MFREE,start); 
Parameters: 

Start First address in heap to free 
Return Code: 


ret Error Code 


Description: The MFREE SVC releases the memory in a heap 
from the address specified to the end of that heap. 
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7.26 OPEN 


C Interface: 


UWORD flags; 
BYTE *name; 
LONG fnum; 


fnum = s_open(flags,name); 
ret = _osif(F_OPEN,&parmblk): 


parmbik: 


: Parameters: 
option May be used by SPECIAL devices 
flags bit 0: 1 = Delete file/set attributes access 
O = No delete/set access 


bit 1: 1 = Execute access 


OQ = No execute access 
bit 2: 1 = Write access 

0 = No write access 
bit 3: 1 = Read access 

0 = 


No read access 
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name 


Return Code: 


fnum 
ret 


Description: 


Shared 
Exclusive 


bit 4: 


So —_— 
H 


bit 5: 1 = Allow shared reads if shared 
Allow shared R/W if shared 


© 
il 


Shared file pointer 
Unique file pointer 


bit 6: 1 


bit 7: 1 = Reduced access accepted 
Return error on reduced access 


>) 
it 


bits 8 - 12 are reserved (must be 0) 


bit 13: 1 = Force case to media default 


0 = Do not affect name case 
bit 14: 1 = Literal name | 
0 = Prefix substitution allowed 


bit 15 is reserved (must be OQ) 


Address of file, pipe, or device name 


file number 
Error Code 


The OPEN SVC opens an existing file and returns a 
32-bit file number used for subsequent I/O. “File” in 
this context refers to disk files, pipes, and device 
files used. to communicate with printers, mouses, 
consoles, and special devices. FlexOS sets the file 
pointer to 0 when you open the file. 
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Use flag bits 0 through 3 to request the file access 
privileges--read, write, execute, and delete/set. Use 
flags 4, 5, and 6 to set the access mode--shared 
versus exclusive, shared read only versus shared 
read/write when shared, and shared versus unique 
file pointer. The use of these flags to monitor file 
access differs slightly from one type of file to 
another. See the sections in this manual on disk 
file, console, pipe, and special device management 
for the description of flag use with these types of 
files. 


Set flag bit 6 when you want two or more 
processes to share the same file pointer; this 
feature is only available to processes with the same 
family identification number (FID). Each process 
sharing the pointer must have this flag set. When 
this bit is set, the value of flag bit 1 is assumed to 
be 1; the actual value is ignored. 


Set bit 7 to accept reduced access privileges. The 
file’s governing privileges for owner, group, and 
world categories are set when it is created. Reduced 
access is an issue when a disk label’s security flag 
bit is set and you request a privilege level not 
available to a process with your ID and group 
number. Set this flag to 1 if you can accept 
reduced access; FlexOS ANDs the file’s R, W, E, and 
D privileges corresponding to your category with 


those you requested to determine the privileges you 


actually get. Set this flag to 0 if you cannot accept 
reduced access; FlexOS returns an error code when 
the privileges do not match. 
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Files can be opened any number of times.. Each 
open returns a different file number and each must. 
be closed. Use this technique to obtain greater 
access to a file without losing your previous access. 
The standard protection rules do not apply on 
multiple opens of the same file by the same 
process. For example, if you open a file in SHARED, 
READ-ONLY mode, you can later open it in 
EXCLUSIVE, READ-WRITE mode. The protection 
rules still apply, however, with respect to other 
processes attempting to open the file. 


Pipe file’s read and write ends are separate and 
independent of each other. Similarly, a console file 
can be opened for read and write access separately. 
If one process opens a console or pipe file with 
EXCLUSIVE, READ access, another can open it with 
EXCLUSIVE, WRITE access. One end of a pipe file 
can be opened in SHARED mode while the other is 
Opened in EXCLUSIVE: mode. For pipes, how you 
open the file affects the pipe’s operation. 


ORDER 
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7.27 ORDER 


C interface: 


WORD | order; 
LONG fnum; 
ret = s_order(order,fnum); 


ret 


__osif(F_ORDER,&parmbik); 


parmbik: 


Parameters: 
order New virtual console position 
0 = Bottom 
1 = Next to Bottom 
2 = 2nd from Bottom 
n = Nth from Bottom 
-1 = Top 
fnum File number of virtual console to move 


Return Code: 


ret 


Error Code 
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Description: 


The ORDER SVC changes the position of the virtual 
console with file number fnum in a “stack” of sibling 
virtual consoles. The “order” value specifies the 
virtual console’s new position. Use ~-1 to specify 
the top. All other positions are designated by 
number where 0 is the bottom console, 1 the next, 
then 2, and so forth. The Console Resource Manager 
adjusts the position numbers after you make a 
change. 


The initial order of precedence corresponds to the 
order of creation. 
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7.28 OVERLAY 


C interface: 


BYTE *codeadr,*dataadr;: 
LONG fnum, offset; 


ret = s_overlay(fnum,codeadr,dataadr,offset); 


ret = _ osif(F_OVERLAY,&parmbik); 


parmblk: 


| codeadr , 


16 


20 


Parameters: 
fnum File number of the opened file containing one or 
more overlay procedures 
codeadr Address in calling process’s code area in which to 


load the overlay code. 
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dataadr 


offset 


Return Code: 


ret 


Description: 


Address in calling process’s data area in which to 
load the overlay data. 


Byte offset into file of the overlay header. The 


header must be in the same format as the default 


program load image used by the COMMAND SVC. 


Error Code 


The OVERLAY SVC loads the code and data from the 
designated overlay file into the calling process's 
memory. The overlay file is specified by fnum and 
the code and data addresses by the codeadr and 
dataadr pointers, respectively. Use the offset value 
to select a specific overlay within a file containing 
several. Each overlay in a file must have its own 
header. The overlay file must be open and the 
calling process must have EXECUTE privilege. 


An E_MEMORY error is returned if the overlay does 
not fit into the calling process’s code or data area 
Starting at the specified address. 


When the COMMAND SVC detects overlays in the 
program file, it automatically keeps the file open. 
The file number can be found in the ENVIRON table. 
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7.29 READ 


C interface: 


LONG. fnum,offset,bufsiz,nbytes; 
UWORD flags,*delimiters; 
BYTE *buffer,option; 


nbytes = s_read(flags,fnum,buffer,bufsiz,offset); 

-emask = e_read(swi,flags,fnum,buffer,bufsiz,offset); 
nbytes = s_rdelim(flags,fnum,buffer,bufsiz,offset,delimiters); 
ret = __osif(F_READ,&parmblk); 


Looammmanadd 


parmbIk: 


0=sync , | 


buffer 


: delimiters 


Parameters: 


option May be used by SPECIAL devices 
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flags 


bit 0: 1 = Read from device. On disk files 
internal buffers are flushed and 
discarded before reading. On a keyboard 
file, the type ahead buffer is flushed. 
0 = Allow reading from internal buffers 


bit 1: 1 = Read until delimiter 
0 = Not delimited 


bit 2: 1 = Non-destructive read: Read the internal 
buffer contents without removing bytes 
pertinent to keyboard and pipe files only; 
disk file reads are always non-destructive. 
0 = Normal read 


= Preinitialized read 
0 = Normal read 


oy 
= 
ox 
ond 

| 


bit 4: 1 = Include delimiter in buffer 
0 = Exclude delimiter 


bit 5: 1 = Edited read (only relevant when “Read 
until Delimiter” flag is on.) 
0 = Normal Read 
bits 6-7 are reserved (must be 0) 
bits 8 and 9 determine interpretation of the offset field: 
0 = relative to the beginning of file 


1 = relative to the file pointer 
2 = relative to the end of file 


bits 10-15 are reserved (must be Q) 
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swi 
fnum 


buffer 


.bufsiz 


offset 


delimiters 


Return Code: 


nbytes 


Description: 
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Address of software interrupt routine 

File number of file to read 

Address of buffer in which to place information 
Size of buffer in bytes 


Byte offset relative to the position indicated by flag 
bits 8 and 9. Negative offsets are allowed. 


Address of an array of WORD values. This field is 
ignored on non-delimited reads. The first item 
indicates the number of delimiters in the array; 16- 
bit character delimiters follow. If the file being read 
is an 8-bit file, the high byte of each delimiter is 
ignored. Disk files and pipes with a record size of 1 
are considered 8~bit files; files with a record size of 
2 are considered 16-bit files. If the record size is 
greater than 2, a record size error is returned. The 
keyboard mode in the CONSOLE table determines if 
a console file is 8-bit or 16-bit oriented. On other 
devices, the device driver determines if it is an 8-bit 
or 16-bit device. 


Number of bytes read 
Error Code 
The READ SVC extracts data from the specified file. 


Data can be read either sequentially or randomly. 
The offset field is always added to either the 


beginning of a file, the current file pointer, or the 


end of file (see flag bits 8 and 9). You can specify a 
negative offset; this is useful, for example, to reread 
the last record of a file. Set flag bits 8 and 9 to one 
and the file pointer to one to perform sequential 
1/0. 
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LEFT ARROW 
RIGHT ARROW 
DELETE 
BACKSPACE 
CTRL-B 


CTRL-X 


The file pointer is updated on every read to the byte 
position after the transferred data in the file. It is 
initialized to O at OPEN. 


The READ SVC verifies that the offset and bufsiz 
fields are on record boundaries if the file was 
created with a record size. If the values do not fall 
on record boundaries, no characters are read and an 
error code is returned. 


The READ SVC can be called asynchronously on 
character oriented devices such as keyboards and 
special devices if the delimited read flag is not set. 
In this case, the number of characters read is at 
least one before the event is completed. The disk 
system does not support asynchronous READs. The 
pipe system supports asynchronous’ undelimited 
READs and reads as many characters as requested. 


When using the delimited read flag, READ cannot be 
called asynchronously. The buffer size is limited to 
256 bytes. Editing is performed by keyboards on 
delimited reads only. Common delimiters include 
the <carriage return>,. <line feed> and <help> 
keys. The standard editing characters are as 
follows: | 


Move cursor one character to left. 
Move cursor one character to right. 
Delete next character 

Delete previous character 


Move cursor to beginning of line if not at beginning, 
otherwise move to end of line. 


Erase from beginning of line to cursor 
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lf a standard editing key is used as a delimiter, it 
has no effect on the returned buffer. These keys 
can be changed by an application program through 
the use of the XLAT SVC. The OEM that configures 
the system can also set the original editing 


character set. 
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7.30 RENAME 
C Interface: 
UWORD flags; 
BYTE *name,*newname: 


ret = s_rename(flags,name,newname); 


ret = _ osif(F_RENAME,&parmbltk); 


parmblik: 


Parameters: 
flags bits 0 - 12 are reserved 
bit 13: 1 = Force case to media default 
0 = Do not affect name case 
bit 14: 1 = Literal name and new name 
O = Prefix translation allowed 
bit 15 is reserved 
name Address of string containing name of existing file. 
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RENAME 
newname 


Return Code: 


ret 


Description: 
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Address of string containing new name of file. 


Error Code 


The RENAME SVC renames an existing disk file or 
directory. If the file is currently open by another 
process, FlexOS does not ‘rename the file and 
returns an error. For files, if the new name specifies 
another directory, the file is moved to that location. 
This feature is limited to directories on the same 
drive. Attributes, ownership, protection and date 
stamps are not changed. 
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7.31 RETURN 


C Interface: 


LONG 


ret 


ret 
Parameters: 

emask 
Return Code: 


ret 


Description: 


emask; 


s_return(emask); 


__osif(F_RETURN,emask); 


Event mask of completed event 


return code of asynchronous SVC 


The RETURN SVC retrieves the return code of an 
asynchronous SVC. If the event is not complete, 
FlexOS waits for it to complete before returning 
from the RETURN call. Use WAIT or STATUS to 
determine if the event has completed. The return 
code is the code that would have been returned if 
the SVC had not been called synchronously. Once 
the RETURN SVC has been called, the event's emask 
bit is cleared. 


Note: You cannot use RETURN for events with a 
software interrupt (swi). The event’s completion is 
provided to the swi and is not kept available to the 
parent process. 
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7.32 RWAIT 


C Interface: 
RECT 


position 


emask = 
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*region; 


s_rwait(flags,fnum,region); 
e_rwait(swi,flags,fnum,region); 


ret = __osif(F_RWAIT,&parmbik); 


parmblk: 


Parameters: 


flags 


fnum 
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region 


bit 0: 1 = clip to current window 
0 = no clip 


bit 1: 1 = return on exit from rectangle 
0 = return on entry to rectangle 


bits 2-15 are reserved and must be 0. 


File number of open mouse file 
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region RECT structure describing a rectangular area of the 
screen associated with the mouse. : 


Return Code: 


ret Error Code 
Description: The RWAIT SVC allows a process to detect the 
mouse entering or exiting a described region of the 
screen. 
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7.33 SEEK 


C Interface: 


LONG fnum, offset; 
UWORD flags; 


position = s_seek(flags,fnum,offset); 
ret = __ osif(F_SEEK,&parmbik); 


parmbik: 
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Parameters: 


flags 


offset 


Return Code: 


position 


Description: 


bits 0-7 are reserved (must be 0) 
bits 8-9 determine how to interpret the offset field 


0 —- Relative to beginning of file 
1 - Relative to file pointer 
2 - Relative to end of file 


bits 10-15 are reserved 


Number of bytes relative to reference selected in flag 
bits 8 and 9 : . : 


Current position of the file pointer after SEEK call. 


The SEEK SVC either returns or changes the file 
pointer position of the specified file. To get the 
current pointer position, select the “Relative to file 
pointer” option in flag bits 8 and 9 and specify an 
offset of 0. Any other combination of values for flag 
bits 8 and 9 and the offset cause a change in the 


file pointer position. For all SEEK calls, the value 


returned indicates the current file pointer position. 


The offset value can be positive or negative. An 
error is returned, however, if the new _ pointer 
position is less than 0O. If the file consists of 
multibyte records, the offset must fall on a record 
boundary. 
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7.34 SET 


C Interface: 


BYTE table,*buffer; 
LONG id, bufsiz; 

UWORD flags; 

ret = s_set(table,id,buffer,bufsiz); 
ret = _ osif(F_SET,&parmbik); 
parmbik: 


Parameters: 
table Table number 
flags bits 0-7 may be used by SPECIAL drivers 


bits 8-15 are reserved and must be 0 
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id 


buffer 


bufsiz 
Return Code: 
ret 


Description: 


Table identifier (required only when you have more 
than one table with the same number) 


Address of source buffer with new table contents 


Size of buffer in bytes 


Error Code 


The SET SVC changes table contents. The table is 
specified by the table number and, if necessary, an 
id. The id is table dependent; see the individual 
table explanations in Section 8 for the id value of a 
specific table. Not all tables can be modified with 
SET and some tables can only be modified by 
privileged processes. 


If the bufsiz specified is less than the size of the 
table, the buffer contents replace the table contents 
Starting from the beginning of the _ table. The 
remainder of the table is not changed. 
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7.35 SPECIAL 


C Interface: 


UWORD flags; 
LONG : fnum,dbufsiz,pbufsiz,; 
BYTE func,*databuf,*parmbuf; 


ret = s_special(func,flags,fnum,databuf,dbufsiz,parmbuf,pbufsiz) 
emask = e_special(swi,func,flags,fnum,databuf,dbufsiz,parmbuf, 
pbufsiz); 

ret = __osif(F_SPECIAL,&parmbIk): 


parmblk: 


| O=sync | 
Seer | tm | tae 


es 
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Parameters: 


func 


flags 
swi 
fnum 
databuf 
dbufsiz 


parmbuf 


pbufsiz 


Return Code: 


ret 


ret 


SPECIAL function number field: Bits 6 and 7 indicate 
the data flow direction of the databuf and parmbuf 
buffers as follows: 


bit 7--parmbuf bit 6--databuf 
1 = write buffer 1 = write buffer 
O = read buffer 0 = read buffer 


If no data or parameters are to be transferred, set 
the bits to 0. The remainder of the bits in the 
number are determined by the device drivers. 


Depends on type of file; however bits 11, 14, and 15 
are always reserved and must be 0. 


Address of software interrupt routine 
File number returned when device was opened 


Address of data buffer. If dbufsize field is NULL, this 
field is data. 


Size of data buffer in bytes or NULL to indicate that 
data is in databuf field or that there is no data. 


Address of parameter buffer. If pbufsiz field is NULL, 
this field is data. 


Size of parameter buffer or NULL to indicate that 
parameter is in the parmbuf field or that there are 
no parameters. 


Return code depending on type of file 


Error code. 


SPECIAL 


Description: 
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The SPECIAL SVC provides direct access to a device. 
The calling process must have opened the device 
before a SPECIAL function can be used. The function 
number indicates what type of operation to perform. 
SPECIAL requires the driver, not the resource 
manager, to interpret the function number and 
perform the operation. 


Although SPECIAL functions and return codes differ 
according to the driver, the SPECIAL SVC parameter 
block is always formatted as shown above. The 
format rules are as follows: 


® The most significant 2 bits of the func field 
determine the direction of the buffer data flow 
as described in the func description above. 
The lower 6 bits of the func field and flag bits 
0-10, 12, and 13 are driver dependent. 


@ The flags field is a bit map of flags affecting 
the function's mode of operation and are 
typically function dependent. 


@ The databuf and dbufsiz fields make up a buffer 
specifier. If dbufsiz is O (NULLPTR), databuf 
field is a 32 bit data value rather than a pointer. 


@® The data buffer cannot contain pointers. 


@ The parmbuf and pbufsiz fields are also buffer 
specifiers and follow the same rules as the 
databuf and dbufsiz fields. 


There are a maximum of 64 SPECIAL function 
numbers. (This is because only function number bits 
0 through 5 can be used.) The first 32 digits are 
reserved for use by Digital Research Inc. The second 
32 digits are available for use by an OEM. 
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7.35.1 Disk Resource Manager SPECIAL Functions 


The Disk Resource Manager recognizes nine SPECIAL functions for disk 
initialization and raw disk 1/0. These SPECIAL calls allow you to access 
the disk directly, bypassing normal operations and restrictions. You 
must specify OEM-defined parameters, such as sector size or file 
allocation table (FAT) address, to use some functions. 


The parameter blocks for the Disk Resource Manager functions adhere 
to the model shown above but differ in their flag use and buffer 
requirements. Each function description below includes the _ flag 
definitions. Buffer requirements are shown in the parameter block 
illustrations. If a O is shown in the field, there is no corresponding 
parameter. | 


The return code for all Disk Resource Manager functions is either 
E_ SUCCESS or E_IOERRS. 


Note: Before you can perform the SPECIAL disk initialization functions 
1 through 3, you must open the device with exclusive access and call 
SPECIAL function 8. Read, write, and/or set privileges are also required 
as described below. 
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Disk Function 0: Read System Area 


SPECIAL disk function 0 reads in the system area of the disk into the 
data buffer. GET the drive’s DISK table before you call function 0 to 
determine if the system area exists on the disk. The size of the data 
buffer must be greater than or equal to the size of the system area. 
FiexOS requires the user to have disk read privilege to perform this 
function. 


of of tags 
Ss 
2 
12 _ databuf | 
of 
2S 
Parameters: 

flags Bits 0-15: Reserved 
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Disk Function 1: Write System Area 


SPECIAL disk function 1 writes the contents of the data buffer onto the 
system area of the disk. GET the drive’s DISK table to determine if the 
disk has a system area before calling function 1. The size of the data 
buffer must match the size of the system area. You must must open 
the drive in exclusive mode with write privileges and call SPECIAL disk 
function 8 before you can write to the system area. 


ee ee 


Parameters: 


flags Bits 0-15: Reserved 
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Disk Function 2: Format System Area of Disk 


SPECIAL disk function 2 formats the disk’s system area according to 
the convention of the driver. GET the drive’s DISK table to determine 
if the system area exists before calling function 2. You must open the 
drive in exclusive mode with read, write, and set privileges and call 
SPECIAL disk function 8 before you can format the system area. 


Parameter: 


flags Bits 0-15: Reserved 
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Disk Function 3: Format Track 


SPECIAL disk function 3 formats the disk media according to the 
Specifications in the parameter buffer. You must open the drive in 
exclusive mode with read, write, and set privileges and call SPECIAL 
disk function 8 before you can use this function 


Parameters: 
flags Bit O: Reserved 
Bit 1: 1 = Mark the whole track as bad 
Bit 2: 1.= Use C, H, S, and N fields 
Bit 3: 1 = Use HEAD, CYLINDER, BYTESEC, and SECTOR 


fields 


Bits 4-15: Reserved 
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set bit 1 to remove tracks designated bad by the 
manufacturer from file system access. Set flag bit 3 
rather than flag bit 2 and specify the track in the 
head and cylinder fields. The remainder of the fields 
are irrelevant in this operation. 


You select the format locations and characteristics 
in’ the parmbuf (parameter buffer). The data 
structure provides two, mutually exclusive means for 
specifying the starting head, cylinder, sector 
number, and the number of bytes per sector for the 
format operation. The other fields are valid for both 
options. Set flag bit 2 or 3 to select one means over 
the other. 


parmbuf Format: 


HEAD po CYLINDER 


DENS 


SECTRK SECTOR | 


FILL BYTESEC 


a ee ee eee 


HEAD 
CYLINDER 
DENS 


FILL 
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Starting head number 
Starting cylinder number 
Format density where 


0 - Single density 
1 - Double density 


Fill character 
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BYTESEC 
SECTRK 
SECTOR 


C,H, S, & N 


Number of bytes per sector 
Number of sectors per track 


Starting sector number. When you set bit 3, the 
format operation begins with the sector field 
specified here 


a variable length list of 4—byte fields where: 


C is a starting cylinder number 
H is a head number 

S is a starting sector number 

N is the number of bytes/sector 


When you. set bit 2, the format operation begins 
after the sector specified in each entry. The number 
of items in the list is determined by pbufsiz. 


7-101 


Disk Function 4 FlexOS Programmer's Guide 


Disk Function 4: Media Check 


SPECIAL disk function 4 checks to see if the media has changed or if a 
physical or logical error condition exists on the media. You must have 
opened the drive in at least GET-only mode to use this function. (GET- 
only mode is described in Section 2.6 above.) 


oe ee ae 


4 Strum 
| a Tae 


Parameters: 


flags Bits 0-15: Reserved 
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Disk Function 5: Flush Buffers 
SPECIAL disk function 5 writes any updated buffers onto the disk. The 


user must have opened the device, however, no particular privilege is 
required. 


a ee ee 


Parameters: 


flags Bits 0-15: Reserved 
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Disk Function 6: Read Physical Record 


- SPECIAL disk function 6 either reads data from the media into the data 
buffer or verifies the data is valid; flag bit 2 determines which 
operation is performed. The media starting point for both operations 
is defined in the parameter buffer by head, sector, and cylinder 
numbers. The dbufsiz value determines how much data is read. 
dbufsiz must be a multiple of the media’s sector size. You must have 
opened the drive with at least read privilege to use function. No data 
is read, however, when you select the verify option. 


eee ee 


| | databuf 
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Parameters: 
flags Bits 0-1: Reserved 
Bit 2: 1 = Verify media 
0 = Read media 
Bits 3-15: Reserved 


The starting head, sector and cylinder numbers are 
specified in the H, S, C fields above. 
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Disk Function 7: Write Physical Record 


SPECIAL disk function 7 writes the data buffer contents to the media. 
The media starting point is specified in the parameter buffer by head, 
sector, and cylinder number. The dbufsiz value determines how much 
data is written. dbufsiz must be a multiple of the media’s sector size. 
You must open the drive in exclusive mode with write access before 
you can use this function. 


databuf 


dbufsiz 


Parameters: 


flags | Bits 0-15: Reserved 


The starting head, sector, and cylinder numbers are 
specified in the H, S, C fields, above. 
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Disk Function 8: Initialize Format 


SPECIAL disk function 8 supplies the file system and the disk driver 
with the drive’s Media Descriptor Block (MDB). This function must be 
called before the user calls SPECIAL disk functions 1, 2, and 3. To 
execute this call, the user must have opened the drive in exclusive 
mode with read, write and set privileges. 


ee ee ee ee 
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Parameters: 


flags Bits 0 - 15: Reserved 


The Media Descriptor Block is epSeulee in the data 
buffer as follows: 


SECTSIZE Size of sectors in bytes 


FIRSTSEC First physical sector number of File Allocation Table 
(FAT) on track 0 


NSECTORS Number of sectors in logical image of disk including 
FATs, directory, and boot record 


SECTRK Number of sectors per track 

SECBLK Number of sectors per block 

NFATS Number of FATs 

FATID FAT identification byte 

NFRECS Number of sectors in a FAT 

DIRSIZE Number of directory entries in the root directory 
NHEADS Number of heads 
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FORMAT Media format according to the following values 


0 = RAW 
1 = 1.5 byte FATs 
2 = 2 byte FATS 
HIDDEN Number of sectors in partitions preceding the 


media’s logical image 


SYSSIZE Number of bytes in the system area. 
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7.35.2 Miscellaneous Resource Manager SPECIAL Functions 


Two SPECIAL functions are provided for accessing serial-type port 
devices when they are serving as subdrivers. Use these functions as 
you would GET and SET to determine the driver’s current values and 
set them. The data structure used for both functions is the PORT table. 


The fnum value for both calls is the file number returned when you 
Open the subdriver’s owner. See Section 6 for the description of the 
owner and the procedure for finding it. 


Miscellaneous Device Function 0: Get Current PORT Table Values 


Use this function to determine the subdriver’s current PORT table 
values. | 


parmbuf 
Parameters: 
parmbuf | Address of buffer to place the PORT table. 
pbufsize Length of the buffer; if the number splits a field, 


that value is not copied. 
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Miscellaneous Device Function 1: Set Port Table Values 


Use this SPECIAL function to set a subdriver’s PORT table values. . 


parmbuf 


Parameters: 


parmbuf Address of buffer with source PORT table values. 
pbufsize Length of the buffer; if the number splits a field, 


that value is not set. 
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7.36 STATUS 


C Interface: 


LONG 
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cmask; 


cmask = s_status(); 


ret = _ osif(F_STATUS,OL); 


Parameters: 


NONE 


Return Code: | 


cmask 


Description: 
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Bit map of completed events 


The STATUS SVC informs the calling process of 
previously initiated asynchronous events that have 
completed and whose return codes have not been 
retrieved by the RETURN SVC. If the event specified 
has a software interrupt (swi), the cmask value for 
that event is 0 rather than 1. (You do not call 
RETURN for events with a software interrupt.) 


Note: STATUS places a heavy burden on the CPU; 
excessive use of STATUS impacts’ program 
performance. | : 
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7.37 SWIRET 


C Interface: 


LONG 


option 


s_swiret(option):; 


ret = __ osif(F_SWIRET,option); 


Parameters: 


option 


Return Code: 
NONE 


Description: 


0 - return to main program at point of interruption 


1 - assume process identity from main program 


The SWIRET SVC is used to return from a software 
interrupt routine (swi). It provides two options: 


O return to the main program at the point of 
interruption 
O retain control of subsequent program execution 


“main program” means the process that made the 
initial asynchronous call. Both options return the 
registers to their values when the process was 
interrupted. 


When you select SWIRET’s second option, the 
software interrupt assumes the main program’s 
process ID and environment, including the stack. 
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Use this option to return to a location in the main 
program other than the point of interruption or to 
assume the entire process identity without returning 
to the main program. Because the current condition 
of the stack is unknown when SWIRET is called, you 
should restore it to a known. place’ before 
proceeding. 


You can exit a program with SWIRET. Specify option - 
1 and call EXIT in your next instruction. 


FlexOS Programmer's Guide | TIMER 


7.38 TIMER 


C Interface: 


UWORD flags; 
LONG time; 


ret = s_timer(flags,time); 
emask = e_timer(swi,flags,time); 


ret = _osif(F_TIMER,&parmblk); 


parmblk: 


Parameters: 


flags bit 0: 1 = absolute 
0 = relative 


bits 1-15: Reserved 


Swi Address of software interrupt routine 


time If bit O = 1 (absolute), number of milliseconds to 
delay after midnight. If bit 0 = O (relative), number of 
milliseconds to delay. 
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Return Code: 
ret 


Description: | 
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Error Code 


The TIMER SVC delays the calling process until the 
specified time or the specified period of time 
expires. Use TIMER asynchronously with bit 0 = 0 
(relative time) when you need a watchdog timer for 
an asynchronous SVC. 


If absolute time is specified and the current time of 
day is beyond it, the process delays until the 
specified time the next day. 
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7.39 WAIT 


C Interface: 


LONG 


events,cmask; 


cmask = s_wait(events); 


ret = _ osif(F_WAIT,events); 


Parameters: 
events 
Return Code: 


cCmask 


Description: 


Logical OR of emasks to wait for 


Bit map of completed events 


The WAIT SVC causes the calling process to wait for 
an asynchronous event to occur. Specify one or 
more events by their emask in the WAIT events 
argument. FlexOS returns when one of these events 
has run to completion. For events that do not have 
a software interrupt, the cmask_ return code 
indicates which event completed. Subsequently, call 
the RETURN SVC to retrieve the return code of the 
completed event. This also releases that emask so 
it can be reused. 


You can wait on events that have a software 
interrupt (swi). However, the event bit in the cmask 
returned is 0 rather than 1 when WAIT returns. Also, 
do not call RETURN to retrieve the completion code 
after WAIT returns--the completion is no longer 
available having already been provided to the swi 
for handling. 


THAN 
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7.40 WRITE 


C Interface: 


LONG fnum,bufsiz,offset,nbytes; 
BYTE option,*buffer; 
UWORD flags; 


nbytes = s_write(flags,fnum,buffer,bufsiz,offset); 
emask = e_write(swi,flags,fnum,buffer,bufsiz,offset); 


ret = __ osif(F_WRITE,&parmblk); 


parmbik: 
o= sync | 
eee [mn [tae 
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Parameters: 
option 


flags 


Swi 
fnum 
buffer 
bufsiz 


offset 


May be used by SPECIAL devices 


bit 0: 


bit 1: 


1 


Flush buffers after WRITE. 
This forces the data to the media. 
lf this is a zero length request, 


WRITE 


the media is updated with any pending 


writes. — 

Allow optimized internal buffering 
Truncate file to size specified in 
Offset field. The bufsiz field 


must be 0 to allow a truncate. 


Do not truncate 


bits 2 - 7 are reserved (must be QO) 


bits 8 and 9 determine how the offset fieid 
is interpreted: 


0 
1 
2 


_ 


Relative to beginning of file 
Relative to file pointer 
Relative to end of file 


bits 10-15 are reserved (must be QO) 


Address of software interrupt routine 


File number of file to write to 


Address of buffer from which to write 


Size in bytes of buffer 


Offset into file to start writing depending on bits 8 


and 9. 
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WRITE 


Return Code: 


nbytes 


Description: 
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Number of bytes written. When nbytes is less than 


_bufsize, an error ocurred during the write operation. 


An error code is returned only if no data was 
written before the error ocurred. 


Error Code 


The WRITE SVC places data into the specified file. 
Flags bits 8 and 9 determine whether the offset 
value is added to the beginning of file, the current 
file pointer, or the end of file. The offset can be a 
negative number, allowing a write to the last record 
of the file. Sequential \/O is performed by writing 
relative to the file pointer with an offset of 0. 


The file pointer is updated on every write to be the 
byte position after the transferred data in the file. It 
is initialized to 0 at OPEN. Use the SEEK SVC to 
determine the current value of the file pointer. 


The WRITE function verifies that the offset and 
bufsiz are on record boundaries if the file was 
created with a record size. No data is written if the 
values do not correspond. 


The disk system has an asynchronous interface to 
allow for I/O redirection from the pipe or console 
systems. However, the disk system does not 
support asynchronous WRITE operations. An 
asynchronous WRITE to disk is slower and requires 
more memory than a synchronous WRITE. 
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7.41 XLAT 


C Interface: 


LONG 


UWORD 


BYTE 


ret 


ret 


parmblk: 


fnum,bufsiz; 
flags; 
“buffer; 


s_xlat(flags,buffer,bufsiz); 


__osif(F_XLAT,&parmbtIk); 


Parameters: 


flags 


buffer 


bufsiz 


bit 0: 1 = replace existing table with buffer contents 
0 = add buffer contents to current table 


bits 1 —- 15 are reserved and must be 0. 


Address of the buffer with the replacement or 
supplemental keystroke translations 


Size of buffer in bytes 
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Return Code: 
ret Error Code 


Description: The XLAT SVC creates, replaces, or supplements a 
key translation table for the console specified by 
fnum. When the CONSOLE table KMODE (offset 2) 
bit 2 is 0, FlexOS translates characters entered from 
the keyboard into the string specified in the key 
translation table. : 


The key translation table consists of an unlimited 
number of 32 byte entries. Each entry is formatted 
as follows: 


[_-—$________________-32 bytes 


Replacement string 


The fields are defined as follows: 


e key: The 16-bit character to be translated; fill 
the high byte with a O for 8-bit input. 


@®nch: A WORD value indicating the number of 
16-bit replacement characters; the maximum 
number of replacement characters is 14 


® replacement: The replacement = string; all 
characters are 16-bit 
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The key translation table is maintained on a: per 
process basis. Child processes inherit their parent's 
table and share it until either process makes a 
change. This allows a parent to set up the 
keyboard environment before an application is run. 
When XLAT is called to change a table shared by 
two processes, FlexOS makes a separate copy for 
the calling process so that the modifications do not 
affect the other process. 


There is no inherent timit to the number of 
translated keys supported for each process. The 
space for these keys are taken out of the Transient 
Program Area (TPA). | 


End of Section 7 
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SECTION 8 


System Tables 


System status and parameter values are available to applications 
through the GET, SET, and LOOKUP SVCs which operate on a set of 
formalized data structures that comprise FlexOS’s system tables. This 
section presents descriptions of the system tables in alphabetical 
order. 


The GET SVC transfers the table to a buffer in the application's 
memory space. The SET SVC changes values in a table. For both 
SVCs, the table is identified by its number and, when that table type 
has more than one version, a unique ID number. The LOOKUP SVC 
searches for and retrieves tables of the same type. Each table that 
can be accessed with LOOKUP has a key value field; use this field to 
specify a starting point for the search. 


The GET, SET, and LOOKUP SVCs will not access all of the system 
tables. Table 8-1 lists each of the system tables and the SVCs used 
to access them. Also listed in Table 8-1 are each table’s number, ID, 
and key value. 
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Table 8-1. System Table Access 


Table No. Unique LOOK 
& Name GET SET ID UP Key Description 

OH PROCESS Xx Xx pid Xx pid Process information 

1H ENVIRON x Xx 0 Process environment 

ZH TIMEDATE xX Xx 0 System time of day 

3H MEMORY x 0 System memory use 
10H PIPE Xx fnum xX key Pipe information 
2Z2OH ODISKFILE X X fnum Xx key Disk file information 
21H OISK x Xx fnum Disk device information 
30H CONSOLE x X -= fnum Console file information 
31H PCONSOLE X Xx fnum Console device information 
32H VCONSOLE xX Xx fnum Xx VCNUM Console information 
40H SYSTEM Xx Xx 0 Global system information 
41H FILNUM Xx fnum X fnum File number’s table 
42H SYSDEF Xx key System logical name table 
43H PROCDEF | Xx key Process logical name table 
44H CMDENV x pid Command environment 
45H DEVICE X key Device information 
46H PATHNAME Xx none Full path name 
71H PRINTER x x fnum Printer device information 
81H PORT x Xx fnum Port device information 
B2H+ SPECIAL x x fnum Special device information 


In the following system table descriptions, only those fields marked 
R/W are read-write; all other fields are read-only. In all bit-mapped 
values the bits for which there are no options are reserved and must 
be 0. 


Note: FlexOS does not maintain memory representations for the 
tables described in this section. The corresponding resource manager 
or driver constructs them. only when you call the GET, SET, or LOOKUP 
SVCs. 3 
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8.1 CMDENV Table 


Number GET? SET? LOOKUP? 
44H Yes No No 


ID: 0 or process ID 


Key: none 
Command File Specification . . . 
Command Tail. . . 


256 = Length in bytes. 


128 


The CMDENV table contains a process’s command file specification and 
command tail. The strings are set by the COMMAND SVC. Both fields 
are 128 bytes in length and the strings are NULL terminated. The file 
specification includes the full pathname. 


You can get the CMDENV table for the calling process or another 


Otherwise, put the process ID of the target in the ID field. 


8-3 


8.2 CONSOLE Table FlexOS Programmer's G 


8.2 CONSOLE Table 


Number GET? SET? LOOKUP? 


30H Yes Yes No 


ID: File number of the console file 
Key: none 


The CONSOLE table describes the screen and keyboard of a con 
file. 


0 1 2 3 | 


CNAME | | 


26 = Length in bytes 


© TAHEAD: Number of characters waiting in type-ahead buffer 
@® SMODE (R/W): Screen modes 


bit 0: 1 
0 


Disable escape sequence decoding 
Select Escape sequences supported 


bit 1: 1 = Characters are 16-bit values 
Characters are 8-bit vaiues 


Convert <LF> to <CR><LF> 


bit 2: 1 
0 = Do not convert <LF> or <CR> 
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@ KMODE (R/W): Keyboard mode 


bit 0: 1 = Disable Control-C 
0 = Control-C attempts external abort 


bit 1: 1 = Disable Control-S/Control-Q 
= Allow Control-—S/Control-Q 


bit 2: 1 = Disable keyboard translation 
0 = Translate keys 


bit 3: 1 = Disable ESC sequence decoding 
0 = Support ESC sequence 


Characters are 16-bit values 
= Characters are 8-bit values 


bit 4: 


SS _ 
] 


bit 5: 1 = Disable echo 
0 = Echo input characters on screen 


bit 6: 1 = Disable CTRL-Z 
0 = CTRL-Z = end of file 


bit 7: 1 = Enable toggle characters 
0 = Disable toggle characters 


bit 8: 1 = Convert <LF> or <CR> to <CR><LF> 
0 = Do not convert <LF> or <CR> 


bit 9: 1 = Do not echo carriage returns 
0 = Echo carriage returns 


bit 10: 1 = Do not echo <CR> on any delimiter 
0 = Echo <CR> on any delimiter 


@® CURROW (R/W): Current cursor row position 
@® CURCOL (R/W): Current cursor column position 
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@ NROWS: Height of virtual screen in character rows 
& NCOLS: Width of virtual screen in character columns 
@ VCNUM: Decimal number of virtual console 


@ TYPE: Type of virtual console 


bit 0: 1 = Graphics capability 
0 = Character only 


bit 1: 1 = No numeric keypad 
Keypad © 


bit 2: 1 = Mouse support 


0 = No mouse support 
bit 3: 1 = Color 
0 = Black and white 


bit 4: 1 = Memory-mapped video 
0 = Serial device 


bit 5: 1 = Currently in graphics mode 
0 = Currently in character mode 


@ CNAME: Physical console device name 


Each console file opened has a corresponding CONSOLE table. The 
TAHEAD, CURROW, and CURCOL values are initialized to 0 when the 
console file is opened. NROWS and NCOLS correspond to the rows and 
columns set in the virtual console. SMODE and KMODE are initialized 
to 0; TYPE and CNAME are inherited from the parent console. 


GET and SET the CONSOLE table using as the ID the file number 
returned when you OPENed the file vcxxx/console. Do not use the file 
number returned when you CREATEd the virtual console. For most 
applications, this file number is contained in the stdout--the screen 
file number--and stdin--the keyboard file number--in the ENVIRON 
table. Stdin and stdout can have the same or different file numbers. 


Use SET to change the cursor position and the screen and keyboard 
modes. 
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8.3 DEVICE Table 


Number GET? SET? LOOKUP? 


45H No No Yes 


ID: none 
Key: Key value assigned by resource manager 


8.3 DEVICE Table 


This table describes a physical device. Each device installed has a 


DEVICE table. All fields are read-only. 


22 = Length in bytes 


@ KEY: Key field for LOOKUP 
® DEVNAME: 10-byte device name 
@® TYPE: Type of device 


OxH —- Kernel drivers 

2xH - Disk drivers 

3xH - Console drivers 

5xH — Extension drivers 
6xH - Network drivers 

7xh — Miscellaneous drivers 
80-FFH — Special drivers 


TYPE 
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@® ACCESS: Access modes 
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bit 0 


bit 1 


bit 2 
bit 3 
bit 4 
bit 5 
bit 6 
bit 7 
bit 8* 


bit 9* 


1 = Delete allowed 
0 = Delete not allowed 


Reserved 


1 = Raw write allowed 
0 = Raw write not allowed 


1 = Raw read allowed 
0 = Raw read not allowed 


1 = Shared access allowed 
0 = Exclusive access only 


1 = Removeable device 
0 = Permanent device 


1 = Device lock (DEVLOCK) allowed 
= Device lock not allowed 


1 = Shared access only 
0 = Exclusive access allowed 


1 = Device partitions allowed 
0 = Device partitions not allowed 


= Verify disk writes 
Do not verify disk writes 


Ce —_ 
I 


bits 10-15 reserved 


* Applicable to disk devices only. 
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® INSTAT: Installation status 


0x00 - Not installed 

0x01 - Requires subdriver 

0x02 - Qwned by the Miscellaneous Resource Manager 
0x03 - Owned by another driver 


@® OWNERID: Significant 16 bits of the key field of the owner's 
DEVICE table entry. Use this value with a LOOKUP to find the 
driver that owns this subdriver. This field is only valid when 
INSTAT has a value of 0x03. 


The DEVNAME, TYPE, ACCESS, and KEY values are established when 
the device is installed and do not change. The ACCESS flags override 
conflicting requests made by programs when they open the device. 


The INSTAT and OWNERID values are also static except for subdrivers 
assigned to different drivers. In this case, the current values are 
subject to change as the driver is linked and unlinked to different 
owners. : 


You must use the LOOKUP SVC to get DEVICE tables. Wildcards can be 
used in the LOOKUP device name specification. 
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8.4 DISK Table 


Number GET? SET? LOOKUP? 
21H Yes" Yes No | 


ID: File number returned by OPEN 

Key: none | 

The DISK table describes a disk driver. All fields are read-only except 
the label options. 
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STATUS 


| LRNID 


NSECTORS 
SECTS/TRACK SECTS/BLOCK 
NFATS FATID 


FORMAT 


78 = Length in bytes 


- 8.4 DISK Table 


@® NAME: Disk device driver name 


@ TYPE: Media type 


bit 0: 


1 = Removable media 
0 = Permanent media 


lOPTIONS: Install options 


bit 0: 


bit 1: 


bit 2: 


bit 3: 


bit 4: 


bit 5: 


bit 6: 


bit 7: 


bit 8: 


bit 9: 


Oo —_ 


1 = Set allowed 
0 = Set not allowed 


Reserved 
1 = Raw write allowed 
0 = Raw write not allowed 
1 = Raw read allowed 

= Raw read not allowed 
Reserved 


1 = Removable device driver 
Permanent device driver 


1 = DEVLOCKs allowed 
0 = DEVLOCKs not allowed 
Reserved 
1 = Partitioned disk driver 
0 = Non-partitioned disk driver 
= Verify after writes 
= Do not verify after writes 
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@® STATUS: Disk status 


bit 0: 


bit 1: 


bit 2: 


bit 3: 


bit 4: 


bit 5: 


Dit 6: 


e LRFID: 


1 
0 


1 


4 


0 


= Disk locked to process 


Disk not locked to process 


‘Disk locked to family 


Disk not locked to family 


Disk opened for exclusive access 
Disk not opened for exclusive access 


= Disk currently in use by other processes 


Disk not currently in use by other processes 


Disk currently in use by processes in other families 
Disk not currently in use by processes in other families 


Disk activated for file system access 


= Disk not activated 


ag Cot oa ee ae 


= File system files currently open 


No open file system files 


Family ID of locking process 


@® LRNID: Network node ID of locking process 


@ LRPID: Process ID of locking process 


@® FREE: Number of bytes of free space on disk/partition 


SIZE: Size in bytes of total file space on disk/partition 


SECTSIZE: Sector size in bytes 


® 
@ 
@ FIRSTSEC: First sector of logical media 
@ 


NSECTORS: Number of sectors on disk 


SECTS/TRACK: Number of sectors per track 


@ SECTS/BLOCK: Number of sectors per block 


® NFATS: Number of File Allocation Tables (FATs) 
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FATID: Iimplementation-dependent value indicating media format 
NFSECTS: Number of sectors per FAT 

DIRSIZE: Maximum number of directory entries in root directory 
NHEADS: Number of heads on disk 


FORMAT: FAT format 


0 - Raw 
1- 1 1/2 byte FATs 
2 - 2 byte FATs 


@® SYSSIZE: Size of system area in bytes 
@ HIDDEN: Number of hidden sectors on partitioned’ disk 
@ LAFLAG: Label flag 


0 — Label does not exist on media 
1 - Label exists 
2 - Return device error on attempts to read label 


@® LAMODE (R/W): Label mode 
bit 0: 1 = File security enabled 
0 = No file security 


bit 1: 1 = Upper and lower case file names 
0 = Upper case file names only 


@ LAUSER (R/W): Label maker's User ID 
@ LAGROUP (R/W): Label maker's Group ID 


@ LABEL (R/W): 11-character label (also referred to as volume) 
name. Bytes 12 through 14 in LABEL data block are ignored. The 
name does not need to be null-terminated. 
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Most of the DISK table’s read-only fields are static. The exceptions 
are: 


@ STATUS which changes as processes lock, unlock, open, and close 
files. | 


@® FREE and DIRSIZE which increase and decrease as files are 
removed and added. 


@® LRFID, LRNID, and LRPID which change with each change in the 
locking process. 


Use the file number returned by OPEN as the ID in your GET and'SET 
Calls. | 


All of the label-related fields are read/write. However, once they have 
been set, only the superuser (user and group IDs 0) or the original 
label setter can make any changes. 
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8.5 DISKFILE Table 


Number GET? SET? | LOOKUP? 
20H Yes Yes Yes 


ID: File number returned by CREATE or OPEN 
Key: Key number assigned by resource manager 


The DISKFILE table describes a disk file. The disk file must be open 
before you can GET its table. To SET values in the table, the calling 
process must have the same USER and GROUP IDs or have GROUP 
and USER numbers 0. Files do not need to be open for the LOOKUP 
SVC. LOOKUP flag bits determine the type of file to search for and are 
used as follows: 


bit 0: 1 - Include HIDDEN files 


t 


0 = Exclude HIDDEN files 


Include SYSTEM files 
Exclude SYSTEM files 


bit 1: 1 
| 0 


bit 2: 1 = Include VOLUME label 
0 = Exclude VOLUME label 


bit 3: 1 = Include directories 
Exclude directories 


i 


bit 4: 1 = Exclude normal files 
include normaii files 
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~MODYEAR | MODMONTH MODDAY 


MODHR | MODMIN MODSEC RESERVED 


48 = Length in bytes . 


@ KEY: Key field for LOOKUP 
@® NAME: Disk file name 
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@® ATTR1 (R/W): The sum of the following file attributes: 


O1H Read-only 

02H Hidden 

04H System 

O8H Volume label 
10H Subdirectory 
20H Archive attribute 
40H Reserved 

80H Reserved 


ATTR2 (R/W): The sum of the following file attributes: 


01H ~~ Security enabled (label only) 
02H Disk supports uppercase and lowercase file names 
(if not set, disk supports uppercase file names only) 


.04H through 80H are reserved. 
RECSIZE: Record size 
USER (R/W**): User ID of owner 
GROUP (R/W**): Group ID of owner 
PROTECT (R/W): File Security Word 
SIZE: File size 
MODYEAR (R/W): Year of last modification 
MODMONTH (R/W): Month of last modification (1 - 12) 
MODDAY (R/W): Day of last modification (1 - 31) 
MODHR (R/W): Hour of last modification (0 - 23) 
MODMIN (R/W): Minute of last modification (0 — 59) 
MODSEC (R/W): Second of last modification (0 — 59) 


** These fields are read/write to a superuser only. 


All DISKFILE values are set and updated by the Disk Resource Manager. 
This does not preclude setting these values yourself. However, you 
should exercise caution when modifying the attributes and record size. 
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8.6 ENVIRON Table 


Number GET? SET? LOOKUP? 
1H Yes Yes No 


ID: 0 
Key: none 


The ENVIRON and PROCESS tables describe the calling process’s 
environment. Although there is some overlap between the two, the 
Standard input, output, error, and overlay file numbers, file security 
word, and requester node numbers are unique to the ENVIRON table. 


0 | 1 2 3 


36 = Length in bytes 


@ STDIN (R/W): Process’s standard input file number 
® STDOUT (R/W): Process’s standard output file number 
@ STDERR (R/W): Process’s standard error file number 
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@® OVERLAY (R/W): Current program’s file number 

@ SECURITY (R/W): Default file security word for CREATE 
@ USER (R/W**): Current User ID 

@ GROUP (R/W**): Current Group ID 

@ FID: Calling process’s family ID 

_® PID: Calling process’s ID 

® RNID (R/W’): Requester process's remote node ID 

® RFID (R/W’): Requester process’s family ID 

@ RPID (R/W’): Requester process’s process ID 


**These fields are read/write for a superuser only. 


The RNID, RFID and RPID fields are used by network server processes 
only. See the FlexNet Network Operating System OEM and 
Programmer's Guide for the description of their use. | 
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8.7 FILNUM Table 


Number GET? SET? LOOKUP? 
41H Yes No Yes 


ID: File number returned by CREATE or OPEN 
Key: File number returned by CREATE or OPEN 


8.7 FILNUM Table 


The FILNUM table provides the table number for a given file number. 
For example, the Console Resource Manager returns the VCONSOLE 
table number when you GET the FILNUM table for a virtual console file. 


4 ACCESS TABNUM 


6 = Length in bytes 


® FNUM: File number and key field for LOOKUP 


* @ ACCESS: Access privileges returned from OPEN call 


bit 0: 1 = Delete/set access 
0 = No delete/set access 


bit 1: 1 = Execute access 


0 = No exécute access 
bit 2: 1 = Write access 
O = No write access 


bit 3: 1 = Read access 
0 = No read 


@ TABNUM: table number for that type of file’s table 
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8.8 MEMORY Table 


3H Yes No No 


umber GET? SET? LOOKUP? 


ID: 0 

Key: none 

The MEMORY table indicates the system memory usage. The FREE and . 
SYSTEM values change as processes use and release memory and the 
resource managers take up transient program area. 


12 = Length in bytes 


@ FREE: Total free memory in bytes 
@ TOTAL: Total memory in bytes 
@ SYSTEM: Size of system memory in bytes 
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8.9 MOUSE Table 


Number GET? SET? LOOKUP? 
33H Yes Yes No 


ID: File number returned by OPEN 
Key: none 


The MOUSE table describes a pointing device. Every installed pointing | 
device has a MOUSE table. The initial values are set by the driver and 
you can set all of them except for the PIXROW and PIXCOL. 


0 1 2 3 


MASK (16 words) 


DATA (16 words) 


84 


@ ROW (R/W): Current row position of mouse 


@ COL (R/W): Current column position of mouse 
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@ KEYSTATE: Keyboard state of the right Shift, left Shift, Control, 
and Alt keys 


Bit 0 right Shift key 
Bit 1 left Shift key 
Bit 2. Control key 
Bit 3 Alt key 


0 - up position 

1 - down position 
PIXROW: Number of mickeys per pixel for rows 
PIXCOL: Number of mickeys per pixel for columns 
CLICK (R/W): Click interval in milliseconds 
HEIGHT (R/W): Height of mouse form 
WIDTH (R/W): Width of mouse form 
HOTROW (R/W): Hot row of mouse form. 
HOTCOL (R/W): Hot column of mouse form 


MASK (R/W): On a bit map screen, a 16 x 16 pixel rectangle that 
masks the effect of the DATA rectangle. 


@ DATA (R/W): On a bit map screen, a 16 x 16 pixel rectangle to 
“BLT” to the screen given the mask. | 


The ROW and COL values are updated by the Console Resource 
Manager to indicate the current mouse location. You can, however, set 
these values to move the mouse form to a location without device 
input. The HEIGHT and WIDTH values have a maximum value of 4, but 
can be less. If either is less, the length of the MASK and DATA fields 
is not affected. 


8-24 


FlexOS Programmer's Guide 8.10 PATHNAME Table 


8.10 PATHNAME Table 


Number GET? SET? LOOKUP? 


46H No No Yes 


ID: none 
Key: none 


The PATHNAME table contains the fully-expanded path name for a 
defined symbol. LOOKUP is the only way to retrieve a PATHNAME 
table; you cannot SET or GET a PATHNAME. 


4 PATHNAME 


124 Po 


128 = Length in bytes. 


The PATHNAME table consists of a single 128 byte field. Only one path 
is ever returned when you lookup a defined symbol. If the symbol 
specified starts with a defined name, the prefix is substituted for the 
symbol. lf the first name in the prefix is itself a defined symbol, the 
substitution is made again. The search and _ substitute routine is 
repeated until no prefix is found for the starting name. 


The SYSDEF and PROCDEF tables are searched when you lookup the 
PATHNAME table. (DEFINE only looks in one or the other.) These 
tables are searched for the first name in the specification only. 


Wildcard characters can be used but they are not expanded; for 
example, as asterisk is interpreted only as an asterisk. 
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8.11 PCONSOLE Table 


Number GET? = SET? LOOKUP? 


31H Yes Yes No 


ID: File number returned by OPEN 
Key: none 
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The PCONSOLE table describes a physical. console device. Each 
console installed has its own PCONSOLE table. All parameters are 


read-only except the country code. 


O- 1 


36 = length in bytes 


@® NAME: Console device name 


nee [runes [ave [exe | 


@® NVC: Current number of virtual consoles 


@ CiD: Physical console ID number 
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PCONSOLE Table 


@ ROWS: On graphic console devices, this is the number of rows of 


pixels. 


On character console devices, this 


character rows and its the same as CROWS. 


is the number of 


@ COLS: On graphic console devices, this is the number of pixels in 


a row. 


On character console devices, this 
character columns and is the same as CCOLS. 


@® CROWS: The number of rows of characters 


@® CCOLS: The number of columns of characters 


@ TYPE: Type of console 


bit 0: 
bit 1: 
bit 2: 
bit 3: 
bit 4: 


bit 5: 


1 = Graphics capability 
0 = Character only 


No numeric keypad 


1 
0 = Keypad 


1 


Mouse supported 
No mouse supported 


= Color 
Black and white 


oe —_ 


1 = Memory-mapped video 
Serial device 


i) 
HN 


1 = Currently in graphics mode 
0 = Currently in character mode 


@ PLANES: Planes supported 


Bit 0: 


Bit 1: 


Bit 2: 


1 = Character plane supported 
0 = No character plane 


1 = Attribute plane supported 
No attribute plane 


© 
iH 


1 = Extension plane supported 
No extension plane 


© 
I 


is the number of 
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® ATTRP: Bit map of attribute plane bits supported 
@ EXTP: Bit map of extension plane bits supported 


@ COUNTRY (R/W): Country code; in applications that support 
multiple character sets, use this value to select a specific set. 
Appendix C lists the country codes. 


@ NFKEYS: Number of function keys supported 

® BUTTONS: Number of mouse buttons supported 

@ SERIAL # Mouse serial number 

e@ MUROW Mouse sensitivity in mickey units per row 


@® MUCOL Mouse sensitivity in mickey units per column 


The PCONSOLE values are set by the driver. The Console Resource 
Manager updates the NVC value as you create and delete virtual 
‘consoles on this console. 


To GET and SET a PCONSOLE table (LOOKUP cannot be used), OPEN 
the device and use the file number returned as the GET and SET ID - 
number. In your OPEN call, the only access mode flag bit you can set 
is bit 0 and you only need set it if you want to change the country 
code. 
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8.12 PIPE Table 


Number GET? SET? LOOKUP? 
10H Yes No Yes 


ID: File number returned by CREATE or OPEN 
Key: Key number assigned by resource manager 


The PIPE table describes a pipe. All fields are set when you create the 
pipe and are read-only. | 


; RECSIZE SECURITY 


20 = Length in bytes 


KEY: Key field for LOOKUP 
NAME: 10-byte pipe name 
SIZE: Internal buffer size of pipe 
RECSIZE: Record size 


SECURITY: File security word 


You can retrieve a pipe table with GET or LOOKUP. Use the the file 
number returned when you CREATEd or OPENed the pipe as your GET 
ID number. In a LOOKUP call, use the pipe name. 
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8.13 PORT Table 


Number GET? SET? LOOKUP? 
81H Yes Yes No 


ID: File number returned by OPEN 
Key: None 7 


0 1 2 3 
| TYPE STATE 
| BAUD MODE CONTROL | RESERVED 


8 = Length in bytes | 


@ TYPE: Type of port 


0 = Undefined 

1 = Standard serial driver 
2 = Character I/O device 

4 = Standard parallel driver 


@ STATE (R/W): Current state of port 


0 = Transmit enable 

1 = Character has been received 
2 = Change in Data Set Ready or Data Carrier Detect 
3 = Parity error 
4 = Overrun error 
5 

6 

7 


= Framing error 
= Carrier present (Data Carrier Detect) — 
= Data Set Ready (DSR) active 
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@ BAUD (R/W): A value selecting the baud rate 


0 = 50 baud 6 = 600 baude 12 = 4800 baud | 
1 = 75 baud 7 = 1200 baud 13 = 7200 baud 
2 = 110 baud 8 = 1800 baud 14 = 9600 baud 
3 = 134.5 baud 9 = 2000 baud 15 = 19200 baud 
4 = 150 baud 10 = 2400 baud 

5 = 300 baud 11 = 3600 baud 


@ MODE (R/W): Bit-mapped description of the word length, parity . 
and stop bits 


Bits 0-1 Bits 2-3 Bits 4-5 

Value Bits/word Stop Bits Parity 

0 5 None. None 

1 6 1 Odd 

2 7 1.5 

3 8 2 Even 

® CONTROL (R/W): Bit-mapped description of serial port control 

parameters 7 

0 = Enable character transmission 

1 = Force Data Terminal Ready low 

2 = Enable character reception 

3 = Force break signal 

4 = Reset error 

5 = Force Request to Send low 


Use the GET and SET SVCs to retrieve and set PORT table values. The 
ID is the file number returned when the device was opened. When the 
port is a subdriver, you cannot access the table directly with GET or 
SET. Instead, use SPECIAL functions 13H and 93H, respectively. 


For standard parallel drivers, the STATE, BAUD, MODE, and CONTROL 
fields are meaningless. 
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8.14 PRINTER Table 


Number GET? SET? =LOOKUP? 
71H Yes Yes No 


ID: File number returned by OPEN 
Key: None 


The PRINTER table describes an installed printer driver. The printer 
driver may drive the physical 1/O port directly or require a subdriver to 
conduct character 1/O. For all bit maps in this table, the least 
significant bit is rightmost. 


0 1 2 3 
PRINTER STATUS 
PAPER. . WIDTH 


SING.PAG LENGTH | 


28 = Length in bytes 


@® PRINTER STATUS: Bit map indicating current status; bits are 
assigned as follows: 


om 


Set Definition Bit Set Definition 
Off line 4 Illegal mode requested 
Out of paper 5 Framing error 
Select error 6 Internal buffer full 
7 


Initialization error Waiting for XON 
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@ MODE (R/W): A bit map used to select the current typeface; the 
bits are assigned as follows: 


Bit Typeface Selected Bit Typeface Selected 
0 - Boldface 4 Superscript 

1 Graphics 5 Condensed 

2 Italic 6 Elongated 

3 Subscript 7 Letter quality 


@ PAPERTYP (R/W): A bit map indicating the current paper type; 
the default is 8 1/2 x 11. The bits are assigned as follows: 


Bit Paper Type 
0 Wide paper 
1 Letterhead 
2 ‘Labels 


@ WIDTH (R/W): Width of paper in columns for all modes except 
graphics; in dots if graphics mode. 


@ LENGTH (R/W): Length of paper in lines 


@® LEG.MODE: Bit map of modes available; bit assignments are the 
same as MODE above. : 


@® SING.PAG (R/W): Single-page paper feed select; non-zero when 
single-page feed mechanism selected. 


@ LPI (R/W): Number of lines printed per inch 


@® NAME: 16-byte field for the brand and mode of the printer in 
ASCII. 


To retrieve a PRINTER table, use the file number returned when the 
device was opened as the GET ID number. 
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8.15 PROCDEF Table 


Number GET? SET? LOOKUP? 
43H © No No | Yes 


ID: none 
Key: Key number assigned by resource manager 


The PROCDEF table shows the prefix defined for a logical name by the 
calling process. The LNAME and PREFIX fields are set by the DEFINE 
call; the key value is set by the resource manager when the name is 


defined. All fields are read-only. 


PREFIX 


138 | | 


142 = Length in bytes 


@ KEY Key field for LOOKUP. 


@ LNAME: 10-byte, null terminated logical name string 


@ PREFIX: 128-byte, null terminated prefix substitution string 


Use LOOKUP to get a PROCDEF table. Use the logical name (wildcards 
can be used) or key value to specify a table. The maximum name and 
prefix length is 9 and 127 characters, respectively; the null character is 


always included in the specification. 
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8.16 PROCESS Table 


Number GET? SET? LOOKUP? 
OH Yes Yes Yes 


ID: Process ID 
Key: Process ID 


The PROCESS and ENVIRON tables combine to describe a process’s 
environment. The PROCESS table values are set when the process is 
created (see the COMMAND SVC description) and maintained by the 
resource managers. All values are read-only except the priority. This 
value can be set by a process with the same USER and GROUP 
numbers or USER and GROUP numbers 0. 
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) 1 2 3 
STATE PRIOR | 
MAXMEM 
FLAGS USER | GROUP | 
PARENT 


4 EVENTS | 
| CODE | 7 


CSIZE 
DATA 
DSIZE 


| HEAP | 


HSIZE 


60 = Length in bytes 
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PID: Process ID 
FID: Process’s family ID 


CID: Physical console device number 


PROCESS Table 


VCID: Process’s virtual console number-—only filled after console 


is opened 
NAME: Process name 


STATE: Process state 


0 - Run 
1 - Waiting 
2 - Terminating 


PRIOR (R/W): Priority 
MAXMEM Maximum memory allowed 
FLAGS: 


bit 0: 1 = System process 
Q = User process 


bit 1: 1 = Locked in memory 
Swappable 


bit 2: = Running in SWI context 


Running in main context 


Oo =_ 


bit 3: 1 = Originally a privileged process! 
0 = Not originally a privileged process 
USER: User number 


GROUP: Group number 


'p privileged process, also called a superuser, is one with USER and GROUP numbers 0. 
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@ PARENT: Parent process ID 


EVENTS: Bit map of events that have completed but whose return 
values have not been retrieved. 


@ CODE: Start of code area in user space 


CSIZE: Size in bytes of code area 


DSIZE: Size in bytes of data area 


2 


@ 

@ 

@ DATA: Start of data area in user space 
& 

@ HEAP: Start of heap area in user space 
® 


HSIZE: Size in bytes of most recently allocated heap area 


Use the process ID as the ID in GET and SET calls and as the key 
value in LOOKUP calls. You can also use the process NAME with 
LOOKUP. A process ID of 0 selects the calling process. 


2information passed to the process in the COMMAND SVC is stored at this location. 
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8.17 SPECIAL Table 


Number GET? SET? LOOKUP? 
82H-FFH Yes Yes No 


ID: File number returned by OPEN 
Key: Key number assigned by resource manager 


SPECIAL tables describe special devices installed. The format and size 
of a SPECIAL table is defined by the OEM and set by the device driver. 
There are two rules, however, for all SPECIAL tables: the first word 
indicates the size of the table and table number is the same number 
as the device type. 
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8.18 SYSDEF Table 


Number GET? SET? LOOKUP? 


42H No No Yes 


ID: none | 
Key: Key number assigned by resource manager 


The SYSDEF table describes the system's logical names. Logical name 
assignments are made with the DEFINE SVC by privileged (USER and 
GROUP numbers are 0) processes. Privileged processes can also 
change existing assignments. 


PREFIX 


138 | | 


142 = Length in bytes 


@ KEY: Key field for LOOKUP. 
@ LNAME (R/W): 10-byte, null terminated Logical name string. 
@ PREFIX (R/W): 128-byte, null terminated prefix substitution string. 


Use LOOKUP to get a SYSTEM table. Use the logical name or key value 
to specify a table. The maximum name and prefix length is 9 and 127 
characters, respectively; the null character is always included in the 


specification. 
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8.19 SYSTEM Table 


Number GET? SET? LOOKUP? 
40H Yes Yes No 


ID: 0 
Key: none 


The SYSTEM table describes the CPU and operating system. All fields 
are read-only except the IDLECNT. This field is read-write to processes 
with USER and GROUP numbers 0 only. 


0 1 2 3 
OSTYPE VERSION | RELEASE 


SERIAL 


IDLECNT 


16 = Length in bytes 


@® CPU: Type of CPU 


1 - Intel 8080 7 - Motorola 68010 
2 -— Intel 8085 8 - Motorola 68020 
3 - Zilog Z80 9 - Intel 80286 

4 - Intel 8086 10 - Intel 80386 

5 - Zilog Z8000 11 - Intel 80186 

6-- Motorola 68000 — 12 - 255 Reserved 


@ OSTYPE: Type of Operating System 


0 FlexOS 
1-255 Reserved 


@ VERSION: Operating system version number 
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@ RELEASE: Release level of version 
@ SERIAL: 8-byte, operating system serial number 
@® IDLECNT (R/W for privileged user only): CPU System idle count 


IDLECNT is a value incremented by the CPU when no process is 
running. Monitor CPU utilization by setting this value to 0 and after a 
known period of time, GETting the count. 


8-42. 


FlexOS Programmer’s Guide 


8.20 TIMEDATE Table 


Number GET? SET? 


2H Yes Yes 


ID;0 
Key: none 


TIMEDATE Table 


LOOKUP? 


No 


The TIMEDATE table contains the system time of day. All fields are 
read/write except WEEKDAY. The time is maintained by the kernel once 
the starting is set. Use SET to establish the starting time. 


12 = Length in bytes 


TIME 
TIMEZONE WEEKDAY RESERVED 


YEAR (R/W): Year; a literal value (for example, 1987 = 1987) 
MONTH (R/W): Month; 1 - 12 | 
DAY (R/W): Day of the month; 1 - 31 

TIME (R/W): Number of milliseconds since midnight 
TIMEZONE (R/W): Minutes from Universal Coordinated Time 
WEEKDAY: Day of the week; 0 = Sunday, 6 = Saturday 


You use an ID value of 0 to GET and SET the TIMEDATE table. 
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8.21 VCONSOLE Table 


Number GET? = SET? LOOKUP? 


32H 


Yes Yes Yes 


ID: File number returned by CREATE 
Key: VCNUM assigned when virtual console created 


The VCONSOLE table describes a virtual console. 
established when you CREATE the console. Use read/write fields to 
modify window size, location on the virtual console, and placement on 


Table values 


the parent console. 


a 
<<a ai 
Per [sorrow [es [non] 


28=Length in bytes 


@® KEY: Key field for LOOKUP 
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MODE (R/W): Window mode 
bit 0: 1 = Freeze borders 
0 = Synchronize borders (See Note 1, below) 


bit 1: 1 = Allow auto view change (See Note 2, below) 
Keep view fixed 


Keep cursor on edge on auto view change 
Center cursor on auto view change 


bit 2: 1 
0 


bit-3: 1 = Auto view change on output 
-Q = Auto view change on input 


VCNUM: Decimal virtual console number 


TYPE: Type of console. 
bit 0: 1 = Graphics capability 
0 = Character only 


bit 1: 1 = No numeric keypad 
: Keypad 


bit 2: Reserved 


bit 3: 1 = Color 
O = Black and white 


bit 4: 1 
0 


Memory-mapped video 
Serial device 


bit 5: 1 = Currently in graphics mode 
O = Currently in character mode 


VIEWROW (R/W): Row coordinate on the virtual console of 
window’s upper lefthand corner 


VIEWCOL (R/W): Column coordinate on ne virtual console of the 
window's upper lefthand corner 
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NROW (R/W): Number of character rows in the window 


NCOL (R/W): Number of character columns in the window 


POSROW (R/W): Row coordinate on parent console of window’s 
upper lefthand corner 


POSCOL (R/W): Column coordinate on parent console of window's 
upper lefthand corner 


ROWS: Number of character rows in the virtual console 
COLS: Number of character columns in the virtual console 
TOP: Height in character rows of the top border 
BOTTOM: Height in character rows of the bottom border 
LEFT: Width in character columns of the left border 


RIGHT: Width in character columns of the right border 


Notes: 


1. 
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Use bit 0 to freeze a border so that intermediate states are not 
displayed when you make changes to the border file contents. 
Before you change the border file contents, set this bit. After you 
have completed the changes, reset the bit. Normally, keep this 
flag at 0 so that the borders change as you make changes to the 
window dimensions and location. 


. Bits 1 through 3 determine whether the window view changes to 


keep the cursor on-screen or the view remains fixed on the same 
virtual console coordinates regardless of cursor location. If the 
cursor leaves the window and bit 2 = 1, bit 3 determines whether 
the view changes when the cursor leaves the view (output) or 
when the application READs the keyboard. 
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Use the file number returned by the CREATE call to GET or SET the 
VCONSOLE table. Alternatively, use the key value in a LOOKUP call. 
Changes made to the VIEWROW, VIEWCOL, NROW, and. NCOL 
immediately affect the shape and position of the window on the virtual 
console. Border files are automatically adjusted accordingly as well. 
Changes to POSROW and POSCOL are immediately reflected on the 
parent console. 


End of Section 8 
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Character Sets and Escape Sequences 


This appendix describes the Console Resource Manager's built-in 
escape sequences and character sets. The presentation begins with 
the description of the 8-bit escape sequences (a superset of the 
VT-52 escape sequences), continues with the description of the 16-bit 
output character set, and concludes with the description of the 16-bit 
input character set. 


Output escape sequence decoding is only available with the WRITE 
SVC. You cannot use COPY or ALTER to output escape sequences. 


The descriptions below cross-reference bits in the CONSOLE table’s 
SMODE and KMODE fields. See Section 8, “System Tables,” for the 
complete description of these fields. 


Ad Escape Sequences 


You select escape sequence decoding to manipulate the screen 
display by setting bits 0 and 1 of the CONSOLE table’s SMODE word to 
0. Escape sequence decoding of keyboard input is selected by setting 
bits 3 and 4 of the CONSOLE Tabie’s KMODE word to 0. 


An escape sequence consists of at least two 8-bit characters, where 
the first is always an ESC (ASCII character 1B hex). The second 
character selects a _ function. Three functions require additional 
numeric values to select a foreground or background color or set the 
cursor position. Table A-1 lists the functions supported and the 
escape sequence that invokes it. 
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Table A-1. Escape Sequence Functions 


ESC Sequence 


<ESC >A 
<ESC>B 
<ESC>C 
<ESC>D 


<ESC>H 


Description 


Cursor Up: Move cursor up to beginning of 
previous line. 


Cursor Down: Move cursor down one line without 
changing column position. 


Cursor Right: Move cursor one character position 
right. 


Cursor Left: Move cursor one character position 
left. 


Cursor Home: Move cursor to first column of first 
line. 


<ESC>I (uppercase i) 


<ESC>j 
<ESC >k 


<ESC>Y(c,)(c,) _ 


<ESC>E 
<ESC>J 


<ESC>K 


Reverse Index: Move cursor up one line without 
changing column position. 


Save Cursor Position: Store current cursor position 
for subsequent restore. 


Restore Cursor Position: Move cursor to position 
previously saved. 


Set Cursor Position: Move cursor to specified 
coordinates; first character is the ASCII equivalent of 
the row number + 31D and second character is 
ASCIl equivalent of column number + 31D. 


Clear Display: Erase entire screen and home cursor. 


Erase to End of Display: Erase from cursor to end 
of display. 


Erase to End of Line: Erase from cursor to end of 
line. : 
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ESC Sequence 


Table A-1. (Continued) 


Description 


<ESC>I (lowercase L) 


<ESC>d 
<ESC>Oo0 
<ESC>L 
<ESC>M 


<ESC>N 


<ESC>bin) 


Erase Entire Line: Erase current line contents. 


Erase Beginning of Display: Erase from beginning 
of display through cursor. 


Erase Beginning of Line: Erase from beginning of 
line through cursor. 


Insert Blank Line: Move current and all suhsequent 
lines down one line; keep cursor on current line. 


Delete Line: Remove current line from display and 
add blank line at bottom. 


Delete Character: Remove character at cursor. 


Set Foreground Color: Set character color for 
current cursor position where n is a decimal value 
that determines the color as follows: . 


0 - Black 8 —- Dark gray 

1 - Blue 9 - Light blue 

2 — Green 10 - Light green 

3 - Cyan 11 - Light cyan 

4 —- Red 12 - Light red 

5 - Magenta 13 - Light magenta 
6 - Brown 14 - Yellow 

7 — Light Gray 15 - White 
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ESC Sequence 


<ESC>c(n) 


<ESC>e 
<ESC>f 
<ESC>p 


<ESC>q 
<ESC>r 


<ESC>u 


Oonh WN = © 


Table A-1. (Continued) 
Description 


Set Background Color: Set screen color for current 
cursor position where n.is a decimal value that 
determines the color as follows: 3 


- Black 

- Blue 

~ Green 

- Cyan 

- Red 

~ Magenta 

- Brown 

7 - Light Gray | 

8 - 15 are the same as O - 7, except the foreground 
blinks. 


Enable Cursor: Show cursor. 
Disable Cursor: Remove cursor. 


Enter Reverse Video Mode: Swap foreground and 
background colors. 


Exit Reserve Video Mode: Return to. original 
foreground and background color scheme. 


Enter Intensify Mode: Turn on the consoles” 
intensity option. 


Exit Intensify Mode: Turn off the console’s intensity 
option. | 
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ESC Sequence 


<ESC>s 


<ESC>t 
<ESC>@ 


<ESC>O 
<ESC>V 


<ESC>W 


Table A-1. (Continued) 
Description 


Enter Blink Mode: Start character blinking for all 
characters. 


Exit Blink Mode: Stop character blinking. 


Enter Insert Mode: Insert subsequent characters 
from current cursor position, moving’ existing 
characters over; characters pushed off end of line 
are lost. 


Exit Insert Mode: Replace existing characters with 
characters entered. 


Wrap at End of Line: Automatically scroll cursor to 
beginning of next line when end of line reached. 


Drop Characters at End of Line: Ignore characters 
entered after end of line reached. | 
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A.2 16-bit Output Character Set 


When SMODE bit 2 is 1, the Console Resource Manager accepts 16-bit 
characters output with the WRITE SVC. Table A-2 defines the 16-bit 
output Enarector set. 


Range 


00xxH 


O1xxH -— OFxxH 


1xxxH 
2xxxXH_- 


Table A-2. Output 16-bit Character Set 


Description 


Same as 8-bit:; each character takes one character | 
position in FRAME. Characters in the range 80H- ~FFH 
are defined on a per country basis. 


Alternate character sets provided by the system 
implementer; each character takes one character 
position where the low byte is stored in the 
Character Plane and the low nibble of the high byte 
is stored in the low nibble of Extension Plane. 


Non-visible characters (take no space). 


Editing characters functionally equivalent to 
the VT-52 ESC sequences defined above: 


2040 Enter insert character mode © 
2041 Cursor up 

2042 Cursor down 

2043 Cursor right 

2044 Cursor left 

2045 Clear display 

2048 Cursor home 

2049 Reverse index 

204A Erase to end of display 

204B_ Erase to end of line 
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Table A-2. (Continued) 


Range Description 


204C 


Insert blank line 


204D Delete line 

204E Delete character 

204F- Exit insert character mode 

2064 Erase beginning of display 

2065 Enable cursor 

2066 Disable cursor 

206A Save cursor position 

206B Restore cursor position 

206C Erase entire line 

206F Erase beginning of line 

2070 Enter reverse video mode 

2071 Exit reverse video mode 

2072 Enter intensify mode 

2073 Enter blink mode 

2074 Exit Dlink mode 

2075 Exit intensify mode 

2076 Wrap at end of line 

2077 Discard at end of line 
3H Set cursor to row xxx (0 origin) 
4xxxH Set cursor to column xxx (0 origin) 
51xxH Set background color to xx (see <ESC>c above) 


52xxH — 7xxxH 
8000H - FCFCH . 


Non-visible characters (take no space) 


16-bit language; each character takes two character 
positions on FRAME (the corresponding Extension 
Plane bytes are modified to indicate byte order). 
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A.3 16-bit Input Character Set 


When the CONSOLE table’s KMODE bit 4 is 1, the Console Resource 
Manager accepts 16-bit characters input with the READ SVC. In a 16- 


bit character, the low byte contains the ASCII character code. The 


high byte is used as shown in Figure A-1. Table A-3 defines the 16- 
bit character set. 


State Bits 
Feet 


t 15 14 13 12 11 10 9 8 
| (O1xx) CTRL Key 
(02xx) ALT Key 


(04xx) SHIFT Key 
(O08xx) reserved 


-bi 


(1Sxx) FUNCTION Keys 
(2Sxx) SPECIAL Characters 
(3xxx) Toggle Characters 
(4xxx) Reserved 

(5xxx) Reserved 

(6xxx) Reserved 

(7xxx) Reserved 


Foreign character set 


Figure A-1. High Byte Bit Usage of 1 6-bit Input Character 


Table A-3 lists the 16-bit characters. The “S” in the table represents 
the value of CTRL, ALT and SHIFT state bits 8, 9, and 10. If these keys 
are depressed when another key is pressed, the corresponding bits 
come on. If the ASCII standard includes this character, the standard 
ASCIl character is generated instead of the state value. 
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Range 


0000 — OOFFH 
1SxxH 


2SXxxH 


Table A-3. 
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16-bit Input Character Set 


Description 


ASCIll character set 


Function keys 


Special keys defined as follows: 


2500 
2S01 

2S02 

2S03 
2S04 
2505 
2S06 
2S07 
2508 
2S09 
2S0A 
2S0B 


2810 
2511 
2812 
2813 
2814 
2815 
2816 
2817 
2818 
2819 


HELP 
WINDOW 
NEXT 
PREVIOUS 
PRINT SCREEN 
BREAK 
REDRAW (screen) 
BEGIN 

END 

INSERT 
DELETE 

SYS REO 


Cursor up 
Cursor down 
Cursor left 
Cursor right 
Page up 
Page down 
Page left 
Page right 
Home 
Reverse tab 
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Table A-3. (Continued) 


Range Description 

2830 Numeric keypad 0 
2831 Numeric keypad 1 
2832 Numeric keypad 2 
2833 Numeric keypad 3 | 
2834 Numeric keypad 4 
2835 Numeric keypad 5 
2836 Numeric keypad 6 
2837 Numeric keypad 7 
2838 Numeric keypad 8 
2839 Numeric keypad 9 
253A Numeric keypad A 
2S3B Numeric keypad B 
2$3C Numeric keypad C 
2S3D Numeric keypad D 
2S3E Numeric keypad E 
2S3F Numeric keypad F 
2S40 Numeric keypad ENTER 
2841 Numeric keypad COMMA 
2842 Numeric keypad MINUS 
2543 Numeric keypad PERIOD 
2S44 Numeric keypad PLUS 

. 2845 Numeric keypad DIVIDE 
2846 Numeric keypad MULTIPLY 
2S47 Numeric keypad EQUAL 
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A 16-bit Input Character Set 
Table A-3. (Continued) 
Description 


Toggle character where xxx defines a toggle key as 
follows: 


12 1 10 9 8 7 0 


A - Action O - OFF 


1- ON 

key 0 - Caps Lock 
1 - Shift Lock 
2 - Scroll Lock 
3 - Num Lock 
10 - Right Shift 
1i - Left Shift 
12 - Insert 
13. - Control 


14 - Alternate 


When the user presses and releases keys 0 - 3 a 
single character is sent. For keys 10 - 14, a 
character is sent when the key is pressed and 
another is sent when it is released. 


Toggle characters are only available if the hardware 
supports them. 
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Table A-3. (Continued) 


Range Description 

4xxxH - 7xxH Reserved 

8xxxH — FCxxH 15-bit Foreign language character sets including 
KANJI. 


End of Appendix A 
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System Return and Error Codes 


All FlexOS SVCs return 32 bit values. A negative number--the high 
order bit is set--indicates an error occurred. The remainder of the 
value is allocated as shown itn Figure B-1. 


"ae Source | ERROR CODE 


High byte Low byte 


High word Low word 


Figure B-1. Error Code Conventions 


In the high order word, only the low byte is significant; the high byte 
is reserved. The low byte indicates the source of the error as indicated 
in Table B-1. By convention, operating system resource managers and 
modules have a zero-value in the low order nibble. 


B Error and Return Codes. 


The 


Table B-1. 


Value 


OOH 
10H 
20H 
21H - 2FH 
30H 
31H - 3FH 
40H 
50H 
51H — 5FH 
60H 
61H - 6FH 
70H 
71H - 7FH 


81H - FEH 


low order word 


Error Source Codes--High Order Word 


Source 


Kernel or Supervisor 

Pipe Resource Manager 

Disk Resource Manager 

Disk Drivers 

Console Resource Manager 
Console Drivers 

Command/Lload 

OEM Extension Resource Manager 
OEM Extension Drivers 

Network Resource Manager 
Network Drivers | 
Miscellaneous Resource Manager: 
Miscellaneous Drivers 

Special Drivers 


eceremmaet coe vtetteemtniee tt memntanete 


indicates the error condition. The codes 
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are 


assigned in ranges of values again to indicate the source. Table B-2 
lists the ranges and their corresponding source. 


B-2 
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Table B-2. Low-order Word Error Code Ranges 


Error Code Range Source 
0000 - 3FFF Drivers 
4000 - 407F Errors Common to All Resource Managers 
4080 - 40FF Supervisor 
4100 - 417F Memory 
4180 - 41FF Kernel 
4200 - 427F Pipe and Miscellaneous Resource Managers 
4280 - 42FF Console System 
4300 - 437F File System 
4400 — FFFF Reserved 


For the source of one of the common error codes, see the low byte in 
the high order word. The remaining tables in this appendix list define 
- the error messages by their source. No error codes are currently 
associated with the Pipe, Console and Miscellaneous Resource 
Managers. 
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Table B-3. 
Mnemonic Code 
E_WPROT 0x00 
E_ UNITNO 0x01 
E READY 0x02 
E_ INVCMD 0x03 
E CRC 0x04 
E_BADPB 0x05 
E SEEK 0x06 
E UNKNOWNMEDIA 0x07 
E SEC_NOTFOUND 0x08 
E_DKATTACH 0x09 
E-WRITEFAULT Ox0A 
E READFAULT 0x0B 
E_GENERAL 0x0C 
E RES1 0x0D 
E_RES2 Ox0E 
E_RES3 Ox0F 
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Driver Error Codes 


Description 


Write protect violation 
Hlegal unit number 

Drive not ready | 
Invalid command issued 
CRC error on I/O 

Bad parameter block 

Seek operation failed 
Unknown media present 
Requested sector not found 
Attachment did not respond 
Write fault 

Read fault 

General failure 

Reserved 

Reserved 

Reserved 
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Table B-4. Error Codes Shared by Resource Managers 


Mnemonic 


E_ SUCCESS 
E_ACCESS 


E_CANCEL 

E_EOF 

E_EXISTS 
E_DEVICE 


E_DEVLOCK 
E_FILENUM 
E_FUNCNUM 
E_IMPLEMENT 
E_INFOTYPE 
E_INIT 

F_ CONFLICT 


E_ MEMORY 
E MISMATCH 


E_NAME 
E_NO_FILE 
E_PARM 
E_RECSIZE 


E_SUBDEV 
E_FLAG 


E_EMEMACCESS 


Code 


OxO0L 
0x4001 


0x4002 
0x4003 
0x4004 
0x4005 


0x4006 
0x4007 
0x4008 
0x4009 
0x400A 
0x400B 
0x400C 


0x400D 
Ox400E 


0x400F 
0x4010 


0x4011 


0x4012 
0x4013 
0x4014 
0x4015 


Description 


No Error 

Cannot access file--ownership 
differences 

Event Cancelled 

End of File 

File (CREATE) or device (INSTALL) exists 
Device does not match; for RENAME, 
on different devices 

Device is LOCKed 

Bad File Number 

Bad function number 

Function not implemented 

Illegal Infotype for this file 

Error on driver initialization 

Cannot access file due to current 
usage; for DELETE on open file or 
directory with files; for INSTALL, 
attempted replacement of driver in use 
Not enough memory available 
Function mismatch--file does not support 
attempted function; for INSTALL, mis- 
match of subdrive type 

Illegal file name specified 

File not found; for CREATE, device or 
directory does not exist 

lilegal parameter specified; for 
EXCEPTION, an illegal number 

Record Size does not match request 
INSTALL only: Sub-drive required 

Bad Flag Number 

Non-existent memory 
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Mnemonic 


E_BOUNDS 
E_EINSTRUCT 
E_EDIVO 
E_EBOUNDEX 
E_OVERFLOW 
E_PRIV 
E_ETRACE 
E_EBREAK 
E_EFLOAT 
E_ESTACK 


E_EGENERAL 


Table B-4. (Continued) 


Code 


0x4016 
0x4017 
0x4018 
0x4019 
Ox401A 
0x401B 
0x401C 
0x401D 
Ox401E 
Ox401F 
0x4020 


Description 


Memory bound error 
legal instruction 
Divide by zero 
Bound exception 
Overflow exception 
Privilege violation 
Trace 

Breakpoint 

Floating point exception 
Stack fault 

General Exception 
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Table B-5. Supervisor and Memory Error Codes 


Mnemonic Code 

E ASYNC 0x4080 
E LOAD 0x4082 
E LOOP 0x4083 
E FULL 0x4084 
E DEFINE . 0x4085 
E UNIT 0x4086 
FE UNWANTED 0x4087 
E DVRTYPE 0x4088 


E LSTACK 0x4089 
Memory Error Codes 


E_POOL 0x4100 
E_BADADD 0x4101 


Description 


Function does not allow 
asynchronous I/O 

Bad load format 

Infinite recursion (99 times) on prefix 
substitution; for INSTALL, subdrive type 
mismatch | 

File number table full 

DEFINE only: illegal name 

Too many driver units 

Driver does not need subdriver 
Driver returns bad driver type 

Stack not defined in load header 


Out of memory pool 
Specified bad address to free 
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Mnemonic 


E_ OVERRUN, 
E_FORCE 
E_PDNAME 
E_PROCINFO 
E LOADTYPE 
E_ADDRESS 
E_EMASK 

E_ COMPLETE 
E_STRL 
E_ABORT 
E_CTRLC 

E_ CONTROL 
E_SWIRET 
E_UNDERRUN 
E_SPACE 


-  E_MEDIACHANGE 
~ —E MEDCHGERR 
E PATH 
E_DEVCONFLICT 
E_ RANGE. 
E_READONLY 
E_DIRNOTEMPTY 
E_BADOFFSET 
E_CORRUPT 
~E_PENDLK 
E RAWMEDIA 
E FILECLOSED 


E_LOCK 
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Table B-6. 


Code 


0x4180 
0x4181 
0x4182 
0x4183 
0x4184 
0x4185 
0x4186 
0x4187 
0x4188 


0x4189 _. 


0x418A 
0x418B 
0x418C 
0x418D 
0x4300 


0x4301 
0x4302 
0x4303 
0x4304 
0x4305 
0x4306 
0x4307 
0x4308 
0x4309 
0x430A 
0x430B 
0x430C 


0x430D 
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Kernel Error Codes 


Description 


Flag already set 

Return code of aborted process 
Process ID not found on abort 
COMMAND only: no procinfo specified 
COMMAND only: invalid loadtype 
CONTROL only: invalid memory access 
Invalid event mask 

Event has not completed | 
Required SRTL could not be found 


Process cannot be terminated 


Process aborted by Ctri-C 

Slave process running | 

Not in SWI context 

Flag already pending 

Insufficient space on disk or in 
directory 

Media change occured 

Detected media change after a write 
Bad path 

Devices locked exclusively 

Address out of range 

RENAME or DELETE on R/O file 
DELETE of non-empty directory 

Bad offset in read, write or seek | 
Corrupted FAT 
Cannot unlock a pending lock 

Not FlexOS media 

File closed before asynchronous lock 
could be completed | 

Lock access conflict 
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Utility return codes follow the same format of operating system error 
return codes, as_ illustrated in Figure B-1, with the following 
exceptions: 


® Utility return codes are positive numbers (LONGS) because the 
high order bit (31) is always zero. 

® When possible, you should use the error codes listed in Table B-7 
in the error code field (bits 0-15). 

@® You can designate given modules within an application in the 
source field (bits 16-23). 


To return errors generated within your application, OR the source field 
(module) with the error code field. For example, to indicate that an 
application has detected a parameter error, uSe: 


return( UR_SOURCE | UR_PARM ); 


Do not OR a source field value with UR_SUCCESS, which is a LONG of 
zeroes. 


Tabie B-7. Utiiity Return Codes 


Mnemonic Code Description 

UR_SOURCE (LONG)O Utility return 

UR_SUCCESS .(LONG)O Success 

URPARM 0x0001 Parameter error 
UR_CONFLICT 0x0002 Contention conflict 
UR_UTERM 0x0003 Terminated by user 
UR:FORMAT 0x0004 Data structure format error 
INTERNAL 0x0005 Internal utility error 
UR_UR_DOSERR 0x0006 PC DOS error 


End of Appendix B 
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Country Codes 


All FlexOS console drivers indicate the country code that is currently 
supported. These country codes are used by applications to 
distinquish character sets, accounting practices, currency symbols 
presentation, date presentation and many other country or region 
dependent practices. 


Code Country or Region 
10 | Afghanistan 
20 Albania 
30 Algeria 
40 Andorra 
50 | Angola 
60 Antigua 
70 Argentina 
80 Austria 
90 Australia 
100 Bahama Islands 
110 Bahrein 
120 Bangladesh 
130 Barbados 
140 Belgium 
150 Bermuda Islands 
160 | Bhutan 
170 Bolivia 
180 Botswana 
190 Brazil 
200 British Honduras 
210 Brunei 
220 Bulgaria 
230 Burma 
240 Burundi 
250 Cameroun 
260 Canada 
270 Central African Republic 


C-1 


C Country Codes 


FlexOS Programmer's Guide 


Code 


280 
290 
300 
310 
320 
330 
340 
350 
360 
370 
380 
390 
400 
410 
420 
430 
440 
450 
460 
470 
480 
490 
500 
510 


520. 


530 
540 
550 


560 


570 
580 
590 
600 
610 


620 


Country or Region 


Ceylon 
Chad 
Chile 
China 
Colombia 
Congo 
Costa Rica 
Cuba 
Cyprus 
Czechoslovakia 
Dahomey 
Denmark 
Dominica 


Dominican Republic 


East Germany 
Ecuador 
Egypt 

El Salvador 
Equatorial Guinea 
Ethiopia 

Fiji 

Finland 

France 

French Guiana 
French Somaliland 
Gabon 
Gambia 
Ghana 

Greece 
Greenland 
Grenada 
Guadeloupe 
Guatemala 
Guinea 
Guyana 
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Code Country or Region 
630 Haiti 
640 Honduras 
650 Hong Kong 
660 Hungary 
670 Iceland 
680 Indonesia 
690 India 
700 Iran 
710 lraq 
720 Ireland 
730 Israel 
740 Italy 
750 Ivory Coast 
760 Jamaica 
770 Japan 
780 Jordan 
790 Kenya 
800 Khmer Republic 
810 Kuwait 
820 Laos 
830 Lebanon 
840 Lesotho 
850 Liberia 
860 Libya 
870 Liechtenstein 
880 Luxembourg 
890 Malagasy Republic 
900 Malaysia 
910 Malawi 
920 Malaysia 
930 Maldive Islands 
940 Mali 
950 Malta 
960 Mauritania 


C Country Codes 


Code 


970 
980 
990 

1000 
1010. 
1020 
1030 
1040 
1050 
1060 
1070 
1080 
1090 
1100 
1110 
1120 
1130 
1140 
1150 
1160 
1170 
1180 
1190 
1200 
1210 
1220 
1230 
1240 
1250 
1260 
1270 
1280 
1290 
1306 
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Country or Region 


Mauritius 
Mexico — 
Moldavian SSR 
Monaco 
Mongolia 
Morocco 
Mozambique 
Nepal 
Netherlands 
New Caledonia 
New Guinea 
New Hebrides 
New Zealand 
Niger 

Nigeria 
Nicaragua 
North Korea 
Norway 

Oman 

Pacific Islands 
Pakistan 
Panama 
Papua 
Paraguay 
People’s Democratic Republic of Yemen 
Peru | 

Philippines 

Poland 

Portugal 

Portuguese Guinea 

Puerto Rico 

Qatar 

Rhodesia 

Rumania 
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Country or Region 


Rwanda 

St. Kitts-Nevis-Anguilla 
St. Lucia 

St. Vincent 

San Marino 

Saudi Arabia 
Senegal 

Sierra Leone 

Sikkim 

Singapore 

Somalia 

South Africa 

South Korea 
South-West Africa | 
Spanish Sahara 
Spain 

Sudan 

Surinan 

Swaziland 

Sweden | 


Switzerland 


Syria 
Tahiti 
Taiwan 
Tanzania 
Thailand 
Tibet 
Timor 
Togo 
Trinidad and Tobago 
Tunisia 
Turkey 
Uganda 


C Country Codes 


Code 


1640 
1650 
1660 
1670 
1680 
1690 
1700 
1710 
1720 


1730. 


1740 
1750 


1760 
1770. 


1780 


Country or Region 


Union of Soviet Socialist Republics 
United Arab Emirates 

United Kingdom | 

United States of America 

Upper Volta 

Uruguay 

Vatican City 

Venezuela 


Vietnam 


West Germany 
Western Samoa 
Yemen Arab Republic 
Yugoslavia 

Zaire 

Zambia 


End of Appendix C 
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Index 


A cancelling event, 7-10 
monitoring event status, 

ABORT, 7-2 ; 77412 

process termination, 5-4 retrieving completion code, 
Access modes, 1-20 7=85 

AR (shared read), 1-20 Attribute plane, 3-6 

ARW (shared read/write), 1-20 background color, 3-7 

default, 1-20 byte format, 3-7 

devices, 6-3 character blinking, 3-8 

EX. (exclusive), 1-20 | foreground color, 3-7 

multiple opens, 2-7 Attributes (disk files only), 2-2 

setting, 7-70 
Access privileges, 1-19 

available, 1-19 | B 

before OPEN, 2-5 

disk label, 2-4 BACKSPACE key, 7-81 

Boot:, i-16 


levels, 1-19 
Border files 


pipes, 4-2 
reduced, 1-20, 7-72 — dimensions, 3-26 
requesting, 7-70 Borders 
rules and restrictions, 2-6 bottom size, 8-46 
setting for devices, 7-53 freeze, 8-44 

left size, 8-46 


to directories, 2-5 
ALTER, 7-4 reserved file names, 3-24 


memory FRAME modification, right size, 8-46 


3-13 synchronize, 8-44 
operation, 3-13 top size, 8-46 
Buttons 


plane byte operations, 7-6 


screen FRAME modification, (mouse) waiting on, 7-7 
3-13 BWAIT, 7-7 


Archive attribute, 2-3 button specification, 3-19 
Asynchronous SVC clicks description, 7-8 
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clicks use, 3-20 

event completion, 3-20 

event specification, 3-19 
mask and state example, 3-20 
mask description, 7-8 

mask specification, 3-19 
selecting buttons, 3-19, 7-8 
State specification, 3-20 


C 


C interface 
data structure representation, 
t=5 
data types, 1-1 
SVC form, 1-7 
CANCEL, 7-10 
Case sensitivity, 1-13 
Chained procedure, 5-3 
Character blinking, 3-8 
Character plane, 3-6 
Character plane 
cell number, 3-8 
Child consoles, 3-22 
Child process, 5-2, 5-3 
CID, 8-37 
CLOSE, 7-11 
affects of, 7-12 
console file, 3-27 
device error, 7-12 
partial, 7-12 
CMDENV Table, 8-3 | 
COMMAND, 7-14 
access privilege requirements, 
Y dead 
asynchronous, 5-4 
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chained procedure, 5-3 
child process, 5-3 
creating processes, 5-3 
procedure, 5-3 
program load options, 5-3 
standard files, 1-18, 3-2 
synchronous, 5-4 
Command specification, 7-15 
Command tail, 7-15, 8-3 
Completion code 
retrieving, 7-85 
specification, 7-45 
Console 
dimensions, 8-5 
keystroke translation, 7-121 
modifying screen, 7-4, 7-24 
name, 8-6 
passing keyboard ownership, 
7-49 © 
returning keyboard ownership, 
7-57 
screen and keyboard modes, 
8-4 
type, 8-6 
virtual console number, 8-6 
Console files 
access modes and privileges, 
3-2 
closing, 3-27 
CONSOLE Table, 8-4 
diagram, 3-12 
how to get and set, 3-12 
source for read-only values, 
3713 
TAHEAD, 3-15 
Consoles 
character modes, 3-2 


console files, 3-1 
dimensions, 3-24 
file naming, 3-24 
physical, 8-26 
related SVCs, 3-2 
related tables, 3-3 
type of, 8-45 
CONTROL, 7-19 


access privilege requirements, 


277 
options, 7-20 
COPY, 7-24 
memory FRAME specification, 
3-14 
Operation, 3-14 
screen FRAME specification, 
3-14 
CPU 
idle count, 8-42 
type, 8-41 
CREATE, 7-26 
pipes, 4-2 
virtual consoles, 3-22, 7-30 - 
CTRL-B, 7-81 
CTRL-C 
trapping, 7-3 
CTRL-X, 7-81 
Cursor 
location, 3-13, 8-5 
keeping in window, 3-26 
tracking, 8-45 
updating location, 3-15 


‘'D 


Data Structures, 1-5 


Data types, 1-1 
Date, 8-43 
Debugging, 7-19 
Default:, 1-16 
DEFINE, 7-33 
device substitution, 7-35 - 
DELETE, 7-36 
access privilege requirements, 
2-7 
open files, 1-21 
required privileges, 1-21 
virtual consoles, 3-27 | 
DELETE key, 7-81 
Delimiters, 3-16, 7-80 
Device drivers 
installing, 7-53 
Device names, 1-12 
case sensitivity, 1-13 


— DEVICE Table, 8-7 


OWNERID, 6-6 

Devices 
access modes, 8-8 - 
access privileges, 6-2 
direct access, 7-92 
enabling for DEVLOCK, 7-53 
enabling for raw I/O, 7-53 
installation, 6-4 
installation status, 8-9 
installing drivers, 7-53 
linking subdrivers, 7-53 
locking/unlocking, 7-38 
name, 8-7 
opening, 6-2, 7-70 
owner ID, 8-9 
related SVCs, 6-1 
related tables, 6-1 
setting access privileges, 7-53 
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types, 8-7 
DEVLOCK, 7-38 
enabling for, 7-53 
miscellaneous devices, 6-3 
options, 2-10 
Directories 
access privileges, 2-5 
creating, 7-26 
deleting, 7-36 
naming, 1-12 
renaming, 7-83 
DISABLE, 7-40 
Disk buffers 
flushing, 7-103 
Disk device 
reading from, 2-8 
writing to, 2-8 
Disk directories 
abbreviations, 1-12 
Disk drive: 
access modes, 2-9 
current status, 8-13 
checking contents, 7-102 


entries in root directory, 8-14 


exclusive mode, 2-10 
FAT ID, 8-14 
first sector, 8-13 


formatting system area, 7-98 


formatting tracks, 7-99 
free space, 8-13 
GET-only mode, 2-9 
hidden sectors, 8-14 


install options selected, 8-12 


label contents, 8-14 
locked information, 8-13 
media format, 8-14 


Media Descriptor Block, 7-107 
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name, 8-12 

number of FATs, 8-13 
number of heads, 8-14 
number of sectors, 8-13 
opening, 2-9 

partition size, 8-13 

raw read, 7-104 

raw write, 7-106 

reading system area, 7-96 
sector size, 8-13 
sectors/block, 8-13 
sectors/FAT, 8-14 
sectors/track, 8-13 
setting for verify after write, 


7253 
setting Media Descriptor 
Block, 7-107 


shared read-only mode, 2-10 
size of system area, 8-14 
total file space, 8-13 

type, 8-12 

writing system area, 7-97 


Disk files 


attributes, 2-2, 8-18 

File Security Word, 8-18 
group and user IDs, 8-18 
group ID, 2-3 © 

initiating access, 2-2 
lock modes, 7-61 

locking and unlocking, 7-60 
modification date, 8-18 
multiple opens, 2-7 | 
ownership rights, 1-19 
record size, 2-3, 8-18 
removing all locks, 7-62 
security, 2-3 

setting attributes, 2-2 


shared access, 2-7 
size, 8-18 
user ID, 2-3 
Disk label, 2-3, 2-4 
selecting options, 2-4 
set mode requirements, 2-10 
Disk media 
characteristics, 2-3 
direct access, 2-8 
raw |/O, 2-8 
Disk Resource Manager 
SVCs, 2-1 
Disk security 
limiting raw I/O, 2-10 
DISK Table, 8-10 
DISKFILE Table, 8-16 
Drivers | 
installation, 6-4 


E 


E_ bwait, 7-7 

E_ command, 7-14 

E__control, 7-19 

E lock, 7-60 

E_ open, 7-70 

E_ read, 7-78 

E_rwait, 7-86 

E_termevent, 7-2 

E_ timer, 7-115 

E__write, 7-118 

ENABLE, 7-41 

ENVIRON Table, 8-19 

Escape sequences 
output, 3-15 


Events 

cancelling, 7-10 

getting completion status, 

7-112 

Outstanding, 8-38 

waiting on completion, 7-117 
EXCEPTION, 7-42 
EXIT, 7-45 

from a swi, 1-11 
Extension plane 

byte format, 3-8 
External abort 

trapping, 7-3 


F 


Family identification number 
(FID), 5-2, 8-20, 8-37 
File 
security, 2-4 
File Allocation Tables 
ID, 8-14 
number of, 8-13 
sectors per, 8-14 
File names, 1-12 
case sensitivity, 1-13 
logical name substitution, | 
1-16 
reserved, 1-16 
wildcards, 1-14 
File number, 1-17 
File pointer, 1-21 
after READ, 7-80 
after WRITE, 7-120 
determining location, 1-21 
getting current value, 7-88 
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.initial value, 7-71 
pipes, 4-5 

setting , 7-88 

setting location, 1-21 
shared, 7-72 


shared versus unique, 1-21 


File security, 2-3, 2-6 
default, 8-20 

for pipes, 4-2 
format, 1-19 

setting, 7-28 

File specification, 1-12 
node, 1-12 

path, 1-12 

root directory, 1-12 
subdirectory, 1-12 


Files 


access mode, 8-21 
closing, 7-11 

console, 3-24 

creating, 7-26 

deleting, 1-21, 7-36 

disk file lock modes, 7-61 
disk file management, 2-1 
file pointers, 1-21 

locking disk files, 7-60 
name specification, 7-28 
number, 1-17 

opening, 1-17, 7-70 
random access, 1-21 


record size specification, 7-28 
removing all disk file locks, 


7-62 
renaming, 7-83 


reserved console names, 3-24 


reserving contiguous disk 
space, 7-29 
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security specification, 7-28 
sequential access, 1-21 
setting size, 7-29 
standard, 1-16 
truncating, 7-119 
unlocking disk files, 7-60 
FILNUM Table, 8-21 
Flags | 
bit ordering, 1-23 
FlexOS 
idle count, 8-42 
release level, 8-42 
version number, 8-41 
FRAME 
attribute plane, 3-6 
C structure, 3-9 
changing rectangle, 7-4 
character plane, 3-6 
copying rectangles, 7-24 
dimensions, 3-10 
Extension plane, 3-8 
memory, 3-10 
modification with ALTER, 3-13. 
modification with COPY, 3-14 
plane use flag, 3-10 
planes, 3-5 
screen, 3-10 
structure diagrain, 3-9 
File Security Word (FSW), 2-3, 
7-28 


G 


GET, 7-47 


access privilege requirements, 
2-6 | 
table number specification, 
7-48 
GIVE, 7-49 
Group ID, 2-3 
GSX, 7-51 


H 


Heap 
adding a new, 7-66 
current size, 8-38 
decreasing size of, 7-69 
expanding, 7-66 
initial contents, 7-15 
Starting address, 8-38 
Heap management, 5-5 
Hidden attribute, 2-2 
Hotspot 
location within mouse form, 
3-18 


Idle count, 8-42 
INSTALL, 7-53 
disk security options, 2-10 
options, 6-5 
Interrupt condition numbers, 
7-43 
Interrupt Service Routine (ISR), 
7-42 


K 

KCTRL, 7-57 

Kernel, 1-29 

Key translation, 7-121. 

Keyboard 
input delimiters, 3-16 
mode, 8-5 
passing ownership, 7-49 
returning ownership, 7-57 - 
type-ahead buffer, 3-15 

KMODE, 8-5 | 
initialization value, 3-13 


L 


LEFT ARROW key, 7-81 
Line editing characters, 7-81 
LOCK, 7-60 
Lock modes, 7-61 
Logical names 
default devices, 7-35 
defining, 7-33 
delimiters, 1-17 
global, 1-17, 8-40 
passing to child process, 1-17 
prefix string, 8-34 
process only, 8-34 
process-related, 1-17 
replacement procedure, 1-17 | 
specification, 7-34 
subtitution, 1-16 
LOOKUP, 7-63 
access privilege requirements, 
2-6 
directories, 8-16 
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hidden files, 8-16 
include label, 8-16 
name case sensitivity, 7-65 
system files, 8-16 
wildcard use, 1-15 


M 


MALLOC, 7-66 
adding new heap, 5-5 
increasing existing heap, 5-5 
'“MCTRL, 7-57 © ) 
Media Descriptor Block (MDB), 
7-107 
Media format, 8-14 
Memory 
allocation at process 
termination, 7-45 
free bytes, 8-22 
increasing heap, 7-66 
operating system size, 8-22 
total bytes, 8-22 
MEMORY Table, 8-22 
Message Window, 3-27 
MFREE, 7-69 | 
Miscellaneous device 
get subdriver PORT table, 
7-110 
set subdriver PORT table, 
7-111 
Miscellaneous devices (see 
Devices), 6-1 
Mouse, 7-86 
driver loading requirements, 
3717 
getting location, 3-18 
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opening, 3-19 
reserved file name, 3-24 
setting location, 3-18 
virtual console number, 3-19 
waiting on clicks, 7-7 
MOUSE Table, 8-23 
Mutual exclusion, 4-6 


N 


Names 
case sensitivity, 1-13 
reserved, 1-16 

Node names, 1-12 


O 


OPEN, 7-70 
access privileges, 1-20 
devices, 6-2 
disk drive, 2-9 
multiple, 2-7 
pipes, 4-3 

ORDER, 7-74 


—Osif, 1-4, 1-5 


Overlay, 1-18, 7-76 
access privilege requirements, 
27] 
current file number, 8-20 
file number, 1-18 
loading, 7-76 
OWNERID, 6-6 


Parameter block 
diagram, 1-7 
Parent consoles, 3-22 
Parent process, 5-2, 8-38 
Partition size, 8-13 
Path, 1-12, 8-25 
item delimiters, 1-17 
PATHNAME Table, 8-25 
PCONSOLE Table, 8-26 
Physical console, 8-26 
attribute plane bits, 8-28 
character rows and columns, 
8-27 
country code, 8-28 
extension plane bits, 8-28 
ID number, 8-26 
name, 8-26 
number of function keys, 8-28 
number of rows and columns, 


— 8-27 
number of virtual consoles, 
8-26 
planes supported, 8-27 
type of, 8-27 
Pi:, 4-1 


PID, 5-2, 8-20, 8-37 

PIPE Table, 8-29 

Pipes 
access modes, 4-3 
access privileges, 4-2 
creating, 7-26 © 
deleting, 4-2, 7-36 
File Security Word, 8-29 
name, 4-2, 8-29 
non-destructive READ, 4-7 
record size, 4-2, 8-29 
related SVCs, 4-1 


shared file pointer, 4-3 
size, 4-2, 8-29 
size specification, 7-29 
used for mutual exclusion, 4-6 
zero length buffers, 4-6 
Planes 
byte or array flag, 3-10 
changing cells, 7-4 
PORT Table, 8-30 
Ports 
baud rate, 8-31 
control parameters, 8-31 
current status, 8-30 
serial mode, 8-31 
type, 8-30 
Prefix string, 8-34, 8-40 
specification, 7-34 
PRINTER Table, 8-32 
Printers 
name, 8-33 
paper type, 8-33 
Status, 8-32 
typeface mode, 8-32 


Priority (process), 1-29, 7-16, 


7-18, 8-37 

Prn:, 1-16, 6-2 
PROCDEF Table, 8-34 

changing entries, 7-33 

scanning, 8-25 

source, 1-17 
Procedure, 5-3 
Process ID, 5-2, 8-37 
PROCESS Table, 8-35. 
Processes 

aborting, 7-2 

child, 5-2 

code area, 8-38 
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command file specification, synchronization with pipes, 


8-3 4-6 

completion code, 7-45 terminating, 5-4, 7-45 
creating, 5-3, 7-14 type of, 8-37 
current family ID, 8-20 user ID, 8-37 | 
current process ID, 8-20 user priority number, 1-29 
current state, 8-37 virtual console number, 8-37 
current user and group ID, Program — 

— 8-20 code area, 8-38 
data area, 8-38 data area, 8-38 
decreasing heap, 5-5 heap, 8-38 
defined logical names, 8-34 load options, 5-3 


family ID, 5-2, 8-37 
group ID, 8-37 
heap, 8-38 Q 
increasing heap, 5-5, 7-66 
loading overlays, 7-76 
maximum memory, 8-37 
maximum memory 
specification, 7-16 
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Random file access, 1-21 


memory at termination, 7-45 may find 
: . enabling for, 7-53 
name, 8-37 
eee READ, 7-78 
name specification, 7-16 rivil ST 
Outstanding events, 8-38 aes Se ‘ 


parent, 5-2, 8-38 

physical console number, 8-37 
PID, 7-16, 8-37 

priority, 1-29, 7-16, 8-37 
priority numbers, 7-18 
process ID, 5-2 

related SVCs, 5-1 

related tables, 5-1 
relationships, 5-2 

return code, 7-45 
scheduling, 1-29, 7-115 
source PROCDEF table, 1-17 
states, 1-24 | 


delimiters, 3-16, 7-80 
disk device, 2-8 
enabling for delimiters, 7-79 
from keyboard, 3-16 | 
line editing characters, 7-8] 
miscellaneous devices, 6-3 
pipes, 4-5 j 
Read-only attribute, 2-2 
Record size, 2-3 
Record_size, 7-26 
RECT 
C structure, 3-11 
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dimensions, 3-11 

structure diagram, 3-11 
Reduced access privileges, 7-72 
Release level, 8-42 
RENAME, 7-83 

access privilege requirements, 

2-7 

Resource Managers, 1-28 
RETURN, 7-85 

limitation, 1-10 
Return code, 1-8 

specification, 7-45 
RIGHT ARROW key, 7-81 
Root directory 

abbreviation, 1-12 © 

number of entries in, 8-14 
RWAIT, 7-86 

clipping region, 3-21 

RECT specification, 3-21 

return value, 3-21 
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S__abort, 7-2 
S__alter, 7-4 
S__bwait, 7-7 
S__cancel, 7-10 
S__close, 7-11 
S__command, 7-14 
S__control, 7-19 
S_ copy, 7-24 
S__create, 7-26 
S__define, 7-33 
S_delete, 7-36 
S__devlock, 7-38 
S__disable, 7-40 


S enable, 7-41 
S__exception, 7-42: 
S__exit, 7-45 
S__get, 7-47 
S__ give, 7-49 
S_gsx, 7-51 
S_install, 7-53 
S__kctrl, 7-57 
S__lock, 7-60 
S__lookup, 7-63 
S__malloc, 7-66 
S_mectrl, 7-57 
S_mfree, 7-69 
S__open, 7-70 
S__order, 7-74 
S__ overlay, 7-76 
S__rdelim, 7-78 
S__read, 7-78 
S rename, 7-83 
S__return, 7-85 
S_rwait, 7-86 
S__seek, 7-88 
S__set, 7-90 
S__special, 7-92 
S__status, 7-112 
S__swiret, 7-113 
S__timer, 7-115 
S__vccreate, 7-30 
S_wait, 7-117 
S_write, 7-118 
S__xlat, 7-121 
Screen 
changing display, 3-13 
cursor location, 8-5 
colors, 3-7 
mode, 8-4 
Screen_fnum, 7-30 
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searching tables, 7-63 
‘Sectors 
first, 8-13 
number on disk, 8-13 
size, 8-13 
SEEK, 7-88 
Semaphores, 4-6 
Sequential file access, 1-21 
SET, 7-90 


access privilege requirements, 


2-7 
Sibling consoles, 3-22 
SMODE, 8-4 
initialization value, 3-13 
Software Interrupt routine 
disabling, 7-40 
enabling, 7-41 
returning from, 7-113 
Software interrupts, 1-10, 1-11 
SPECIAL, 7-92 
checking media, 7-102 
disk function mode 
requirements, 2-8 
disk functions, 7-95 
disk functions return codes, 
7-95: 2 
flushing disk buffers, 7-103 
formatting disk system area, 
7-98 
formatting tracks, 7-99 
‘Miscellaneous device function 
0, 7-110 
Miscellaneous device function 
1, 7-111 | 
miscellaneous devices, 6-4 
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parameter block specification, 
7-92 
raw disk read, 7-104 
raw disk write, 7-106 
read disk system area, 7-96 
reserved function number bits, 
7-93 
reserved function numbers, 
7-94 
writing disk system area, 7-97, 
7-107 
SPECIAL Table, 8-39 
SPLDVR, 6-2 
Spooling system, 6-2 
Standard files, 1-16 
current numbers, 8-19 
numbers, 1-18: 
source definitions, 1-17 
when opened, 3-2 
STATUS, 7-112 
Stdcmd, 1-16 
Stderr (standard error file), 1-16 
current file number, 8-19 
file number, 1-18 
open mode, 3-2 
open privilege and mode, 1-18 
Stdin (standard input file), 1-16 
current file number, 8-19 
file number, 1-18 
open mode, 3-2 
open privilege and mode, 1-18 
Stdout (standard output file), 
1-16 
current file number, 8-19 
file number, 1-18 
open mode, 3-2 
open privilege and mode, 1-18 


Subdrivers 
getting PORT table values, 
7-110 
linking, 6-4, 7-53 
PORT table access, 6-3 
setting PORT table values, 
7-110 
Superuser 
‘disk access privileges, 2-10 
setting privileges, 1-19 
Supervisor, 1-28 
Supervisor calls 
asynchronous, 1-7 
general form, 1-7 
numbers, 1-3 
return codes, 1-8 
synchronous, 1-7 — 
SVC (see also Supervisor calls), 
1-4 
Swi 
disabling, 7-40 
enabling, 7-41 
exit options, 1-11 
See also software 
interrupts 
SWIRET, 7-113 
SYSDEF Table, 8-40 
access rules, 7-34 
changing entries, 7-33 
modification restrictions, 1-17 
‘scanning, 8-25 
System area 
size of, 8-14 
System attribute, 2-3 
System Data Structures, 8-1 
System overview, 1-27 
SYSTEM Table, 8-41 


System:, 1-16 


Tables, 8-1 


CMDENV, 8-3 
CONSOLE, 8-4 
DEVICE, 8-7 
DISK, 8-10 
DISKFILE, 8-16 
ENVIRON, 8-19 
FILNUM, 8-21 

ID value, 7-48 
lookup, 7-63 
MEMORY, 8-22 
MOUSE, 8-23 
PATHNAME, 8-25 
PCONSOLE, 8-26 
PIPE, 8-29 

PORT, 8-30 
PRINTER, 8-32 
PROCDEF, 8-34 
PROCESS, 8-35 
retrieving, 7-4/7 
setting values, 7-90 
SPECIAL, 8-39 
SYSDEF, 8-40 
SYSTEM, 8-41 
TIMEDATE, 8-43 | 
VCONSOLE, 8-44 


TAHEAD, 3-15 

Time, 8-43 

TIMEDATE Table, 8-43 
TIMER, 7-115 

Tracks 


sectors per, 8-13 


Index-13 


Type-ahead. buffer, 3-15, 8-4 


U 


User ID, 2-3 

User space 
code area, 8-38 
data area, 8-38 
heap, 8-38 


V 


VCID, 8-37 

VCNUM, 8-45 
VCONSOLE Table, 8-44 
Version number, 8-41 
Virtual consoles 


border dimensions, 3-26, 8-46 


border specification, 7-31 
child, 3-22 | 
console file closing, 3-27 
creating, 3-22, 7-30 
Current number, 8-45 
deleting, 3-27, 7-36 
dimensions, 8-46 

display rules, 3-22 
iNlustration, 3-25 
initialization values, 3-24 
name, 3-24 

number, 3-24 

number of, 8-26 

parent, 3-22, 7-31 
relationships, 3-22 
reordering, 7-74 

setting dimensions, 3-24 
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setting window size and 
dimension, 3-25 

Siblings, 3-22 

type of, 8-45 

window location, 8-46 

window mode, 8-44 

window position, 8-45 

window size, 8-46 

windows, 3-25 


Ww 
WAIT, 7-117 


Watchdog timer, 7-116 | 
Wildcard, 1-14 


Windows, 3-25 


border files, 3-26 
cursor tracking, 3-26 
dimensions, 8-46 
mode, 8-44 
position on parent, 8-46 
reference point of view, 8-45 
reserved border file names, 
3-24 | 
setting size and position, 3-25 
Wmessage, 3-27 
WME X — 
wmessage pipe, 3-27 
WRITE, 7-118 
access privilege requirements, 
2-7 
disk device, 2-8 
miscellaneous devices, 6-4 
pipes, 4-5 
to screen, 3-15 
with redirection, 3-15 
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